envio 3.10.0 → 3.11.0

package/src/TestIndexer.res.mjs

@@ -268,16 +268,17 @@ function parseBlockRange(chainIdStr, config, rawChainConfig, progressBlock) {
     Stdlib_JsError.throwWithMessage(`Chain ` + chainIdStr + ` is not configured in config.yaml`);
   }
   let configChain = ChainMap.get(config.chainMap, chain);
+  let configStartBlock = Config.startBlockOrZero(configChain);
   let sb = rawChainConfig.startBlock;
   let startBlock = sb !== undefined ? sb : (
-      progressBlock !== undefined ? progressBlock + 1 | 0 : configChain.startBlock
+      progressBlock !== undefined ? progressBlock + 1 | 0 : configStartBlock
     );
   let eb = rawChainConfig.endBlock;
   let endBlock = eb !== undefined ? eb : (
       Stdlib_Option.isSome(rawChainConfig.simulate) ? getSimulateEndBlock(Stdlib_Option.getOrThrow(rawChainConfig.simulate, undefined), config, startBlock) : undefined
     );
-  if (startBlock < configChain.startBlock) {
-    Stdlib_JsError.throwWithMessage(`Invalid block range for chain ` + chainIdStr + `: startBlock (` + startBlock.toString() + `) is less than config.startBlock (` + configChain.startBlock.toString() + `). ` + (`Either use startBlock >= ` + configChain.startBlock.toString() + ` or create a new test indexer with createTestIndexer().`));
+  if (startBlock < configStartBlock) {
+    Stdlib_JsError.throwWithMessage(`Invalid block range for chain ` + chainIdStr + `: startBlock (` + startBlock.toString() + `) is less than config.startBlock (` + configStartBlock.toString() + `). ` + (`Either use startBlock >= ` + configStartBlock.toString() + ` or create a new test indexer with createTestIndexer().`));
   }
   let match = configChain.endBlock;
   if (endBlock !== undefined && match !== undefined && endBlock > match) {
@@ -480,7 +481,7 @@ function createTestIndexer() {
       value: chainConfig.id
     }), "startBlock", {
       enumerable: true,
-      value: chainConfig.startBlock
+      value: Config.startBlockOrZero(chainConfig)
     }), "endBlock", {
       enumerable: true,
       value: chainConfig.endBlock

package/src/db/InternalTable.res

@@ -272,7 +272,7 @@ module Chains = {
     {
       id: chainConfig.id,
       ecosystem: (chainConfig.ecosystem: Ecosystem.name :> string),
-      startBlock: chainConfig.startBlock,
+      startBlock: chainConfig->Config.startBlockOrThrow,
       endBlock: chainConfig.endBlock->Null.fromOption,
       maxReorgDepth: chainConfig.maxReorgDepth,
       blockHeight: 0,

package/src/db/InternalTable.res.mjs

@@ -2,6 +2,7 @@
 
 import * as Table from "./Table.res.mjs";
 import * as Utils from "../Utils.res.mjs";
+import * as Config from "../Config.res.mjs";
 import * as Address from "../Address.res.mjs";
 import * as ChainId from "../ChainId.res.mjs";
 import * as Postgres from "../bindings/Postgres.res.mjs";
@@ -181,7 +182,7 @@ function initialFromConfig(chainConfig) {
   return {
     id: chainConfig.id,
     ecosystem: chainConfig.ecosystem,
-    start_block: chainConfig.startBlock,
+    start_block: Config.startBlockOrThrow(chainConfig),
     end_block: Stdlib_Null.fromOption(chainConfig.endBlock),
     max_reorg_depth: chainConfig.maxReorgDepth,
     source_block: 0,

package/src/sources/ChainSources.res

@@ -0,0 +1,72 @@
+// Sits below `ChainState`/`Persistence` in the module graph so that
+// `StartBlockResolver` (called from `Persistence.init`) can build a chain's
+// sources without a dependency cycle.
+let make = (
+  ~chainConfig: Config.chain,
+  ~onEventRegistrations: array<Internal.onEventRegistration>,
+  ~addressStore: AddressStore.t,
+  ~lowercaseAddresses: bool,
+): array<Source.t> => {
+  let chainId = chainConfig.id
+  switch chainConfig.sourceConfig {
+  | Config.EvmSourceConfig({hypersync, rpcs}) =>
+    let evmRpcs: array<EvmChain.rpc> = rpcs->Array.map((rpc): EvmChain.rpc => {
+      let syncConfig = rpc.syncConfig
+      let ws = rpc.ws
+      let headers = rpc.headers
+      {
+        url: rpc.url,
+        sourceFor: rpc.sourceFor,
+        ?syncConfig,
+        ?ws,
+        ?headers,
+      }
+    })
+    EvmChain.makeSources(
+      ~chainId,
+      ~onEventRegistrations=onEventRegistrations->(
+        Utils.magic: array<Internal.onEventRegistration> => array<Internal.evmOnEventRegistration>
+      ),
+      ~hyperSync=hypersync,
+      ~rpcs=evmRpcs,
+      ~lowercaseAddresses,
+      ~addressStore,
+    )
+  | Config.FuelSourceConfig({hypersync}) => [
+      FuelHyperSyncSource.make({
+        chainId,
+        endpointUrl: hypersync,
+        apiToken: Env.envioApiToken,
+        onEventRegistrations,
+        addressStore,
+      }),
+    ]
+  | Config.SvmSourceConfig({hypersync}) => [
+      SvmHyperSyncSource.make({
+        chainId,
+        endpointUrl: hypersync,
+        apiToken: Env.envioApiToken,
+        onEventRegistrations: onEventRegistrations->(
+          Utils.magic: array<Internal.onEventRegistration> => array<
+            Internal.svmOnEventRegistration,
+          >
+        ),
+        clientTimeoutMillis: Env.hyperSyncClientTimeoutMillis,
+        addressStore,
+      }),
+    ]
+  | Config.SimulateSourceConfig({items, endBlock, ?transactionStore, ?blockStore}) => [
+      SimulateSource.make(
+        ~items,
+        ~endBlock,
+        ~chainId,
+        ~addressStore,
+        ~ecosystem=chainConfig.ecosystem,
+        ~transactionStore,
+        ~blockStore,
+      ),
+    ]
+  // For tests: use ready-to-use sources directly
+  | Config.CustomSources(sources) => sources
+  }
+}

package/src/sources/ChainSources.res.mjs

@@ -0,0 +1,55 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Env from "../Env.res.mjs";
+import * as EvmChain from "./EvmChain.res.mjs";
+import * as SimulateSource from "./SimulateSource.res.mjs";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+import * as SvmHyperSyncSource from "./SvmHyperSyncSource.res.mjs";
+import * as FuelHyperSyncSource from "./FuelHyperSyncSource.res.mjs";
+
+function make(chainConfig, onEventRegistrations, addressStore, lowercaseAddresses) {
+  let chainId = chainConfig.id;
+  let sources = chainConfig.sourceConfig;
+  switch (sources.TAG) {
+    case "EvmSourceConfig" :
+      let evmRpcs = sources.rpcs.map(rpc => {
+        let syncConfig = rpc.syncConfig;
+        let ws = rpc.ws;
+        let headers = rpc.headers;
+        return {
+          url: rpc.url,
+          sourceFor: rpc.sourceFor,
+          syncConfig: syncConfig,
+          ws: ws,
+          headers: headers
+        };
+      });
+      return EvmChain.makeSources(chainId, onEventRegistrations, sources.hypersync, evmRpcs, lowercaseAddresses, addressStore);
+    case "FuelSourceConfig" :
+      return [FuelHyperSyncSource.make({
+          chainId: chainId,
+          endpointUrl: sources.hypersync,
+          apiToken: Env.envioApiToken,
+          onEventRegistrations: onEventRegistrations,
+          addressStore: addressStore
+        })];
+    case "SvmSourceConfig" :
+      return [SvmHyperSyncSource.make({
+          chainId: chainId,
+          endpointUrl: sources.hypersync,
+          apiToken: Env.envioApiToken,
+          onEventRegistrations: onEventRegistrations,
+          clientTimeoutMillis: Env.hyperSyncClientTimeoutMillis,
+          addressStore: addressStore
+        })];
+    case "SimulateSourceConfig" :
+      return [SimulateSource.make(sources.items, sources.endBlock, chainId, addressStore, chainConfig.ecosystem, Primitive_option.some(sources.transactionStore), Primitive_option.some(sources.blockStore))];
+    case "CustomSources" :
+      return sources._0;
+  }
+}
+
+export {
+  make,
+}
+/* Env Not a pure module */

package/src/sources/EvmHyperSyncSource.res

@@ -1,11 +1,5 @@
 open Source
 
-// Surfaced by the HyperSync client (Rust) when HyperSync rejects the API
-// token. The corrupted-token test feeds the real server error (from the query
-// endpoint; the edge no longer 401s malformed tokens on /height) through this
-// check so it can't silently drift away from what getHeightOrThrow guards on.
-let isUnauthorizedError = (message: string) => message->String.includes("401 Unauthorized")
-
 type options = {
   chainId: ChainId.t,
   endpointUrl: string,
@@ -37,13 +31,11 @@ let make = (
 ): t => {
   let name = "HyperSync"
 
-  let apiToken = switch apiToken {
-  | Some(token) => token
-  | None =>
-    JsError.throwWithMessage(`An Envio API token is required for using HyperSync as a data-source.
-Set the ENVIO_API_TOKEN environment variable in your .env file.
-Learn more or get a free Envio API token at: https://envio.dev/app/api-tokens`)
-  }
+  // Per source, so one rejected token is reported once rather than on every
+  // height retry for the life of the process.
+  let unauthorizedWarned = ref(false)
+
+  let apiToken = apiToken->HyperSync.requireApiToken
 
   let client = switch HyperSyncClient.make(
     ~url=endpointUrl,
@@ -213,15 +205,11 @@ Learn more or get a free Envio API token at: https://envio.dev/app/api-tokens`)
       let height = try {
         await client.getHeight()
       } catch {
-      | JsExn(e) =>
-        switch e->JsExn.message {
-        | Some(message) if message->isUnauthorizedError =>
-          Logging.error(`Your ENVIO_API_TOKEN was rejected by HyperSync (401 Unauthorized). The indexer will not be able to fetch events. Update the token and try again using 'envio start' or 'envio dev'. For more info: https://docs.envio.dev/docs/HyperSync/api-tokens`)
-          // Retrying an unauthorized request can never succeed, so block forever
-          let _ = await Promise.make((_, _) => ())
-          0
-        | _ => throw(JsExn(e))
-        }
+      | exn =>
+        exn->HyperSync.rethrowLoggingUnauthorized(
+          ~warned=unauthorizedWarned,
+          ~product="HyperSync",
+        )
       }
       let seconds = timerRef->Performance.secondsSince
       {height, requestStats: [{method: "getHeight", seconds}]}

package/src/sources/EvmHyperSyncSource.res.mjs

@@ -1,33 +1,26 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Source from "./Source.res.mjs";
-import * as Logging from "../Logging.res.mjs";
 import * as HyperSync from "./HyperSync.res.mjs";
 import * as Performance from "../bindings/Performance.res.mjs";
 import * as HyperSyncSSE from "./HyperSyncSSE.res.mjs";
-import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
 import * as ErrorHandling from "../ErrorHandling.res.mjs";
 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 HyperSyncClient from "./HyperSyncClient.res.mjs";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 
-function isUnauthorizedError(message) {
-  return message.includes("401 Unauthorized");
-}
-
 function make(param) {
-  let apiToken = param.apiToken;
   let onEventRegistrations = param.onEventRegistrations;
   let endpointUrl = param.endpointUrl;
   let chainId = param.chainId;
-  let apiToken$1 = apiToken !== undefined ? apiToken : Stdlib_JsError.throwWithMessage(`An Envio API token is required for using HyperSync as a data-source.
-Set the ENVIO_API_TOKEN environment variable in your .env file.
-Learn more or get a free Envio API token at: https://envio.dev/app/api-tokens`);
+  let unauthorizedWarned = {
+    contents: false
+  };
+  let apiToken = HyperSync.requireApiToken(param.apiToken);
   let client;
   try {
-    client = HyperSyncClient.make(endpointUrl, apiToken$1, param.clientTimeoutMillis, HyperSyncClient.Registration.fromOnEventRegistrations(onEventRegistrations), !param.lowercaseAddresses, param.serializationFormat, param.enableQueryCaching, undefined, undefined, undefined, param.logLevel, param.addressStore);
+    client = HyperSyncClient.make(endpointUrl, apiToken, param.clientTimeoutMillis, HyperSyncClient.Registration.fromOnEventRegistrations(onEventRegistrations), !param.lowercaseAddresses, param.serializationFormat, param.enableQueryCaching, undefined, undefined, undefined, param.logLevel, param.addressStore);
   } catch (raw_exn) {
     let exn = Primitive_exceptions.internalToException(raw_exn);
     client = ErrorHandling.mkLogAndRaise(undefined, "Failed to instantiate the hypersync client, please double check your ABI", exn);
@@ -150,33 +143,9 @@ Learn more or get a free Envio API token at: https://envio.dev/app/api-tokens`);
       let height;
       try {
         height = await client.getHeight();
-      } catch (raw_e) {
-        let e = Primitive_exceptions.internalToException(raw_e);
-        if (e.RE_EXN_ID === "JsExn") {
-          let e$1 = e._1;
-          let message = Stdlib_JsExn.message(e$1);
-          if (message !== undefined) {
-            if (message.includes("401 Unauthorized")) {
-              Logging.error(`Your ENVIO_API_TOKEN was rejected by HyperSync (401 Unauthorized). The indexer will not be able to fetch events. Update the token and try again using 'envio start' or 'envio dev'. For more info: https://docs.envio.dev/docs/HyperSync/api-tokens`);
-              await new Promise((param, param$1) => {});
-              height = 0;
-            } else {
-              throw {
-                RE_EXN_ID: "JsExn",
-                _1: e$1,
-                Error: new Error()
-              };
-            }
-          } else {
-            throw {
-              RE_EXN_ID: "JsExn",
-              _1: e$1,
-              Error: new Error()
-            };
-          }
-        } else {
-          throw e;
-        }
+      } catch (raw_exn) {
+        let exn = Primitive_exceptions.internalToException(raw_exn);
+        height = HyperSync.rethrowLoggingUnauthorized(exn, unauthorizedWarned, "HyperSync");
       }
       let seconds = Performance.secondsSince(timerRef);
       return {
@@ -188,12 +157,11 @@ Learn more or get a free Envio API token at: https://envio.dev/app/api-tokens`);
       };
     },
     getItemsOrThrow: getItemsOrThrow,
-    createHeightSubscription: (onHeight, onStatus) => HyperSyncSSE.subscribe(endpointUrl, apiToken$1, onHeight, onStatus)
+    createHeightSubscription: (onHeight, onStatus) => HyperSyncSSE.subscribe(endpointUrl, apiToken, onHeight, onStatus)
   };
 }
 
 export {
-  isUnauthorizedError,
   make,
 }
 /* Source Not a pure module */

package/src/sources/FuelHyperSyncSource.res

@@ -1,7 +1,5 @@
 open Source
 
-let isUnauthorizedError = (message: string) => message->String.includes("401 Unauthorized")
-
 type options = {
   chainId: ChainId.t,
   endpointUrl: string,
@@ -15,13 +13,11 @@ type options = {
 let make = ({chainId, endpointUrl, apiToken, onEventRegistrations, addressStore}: options): t => {
   let name = "HyperFuel"
 
-  let apiToken = switch apiToken {
-  | Some(token) => token
-  | None =>
-    JsError.throwWithMessage(`An Envio API token is required for using HyperFuel as a data-source.
-Set the ENVIO_API_TOKEN environment variable in your .env file.
-Learn more or get a free Envio API token at: https://envio.dev/app/api-tokens`)
-  }
+  // Per source, so one rejected token is reported once rather than on every
+  // height retry for the life of the process.
+  let unauthorizedWarned = ref(false)
+
+  let apiToken = apiToken->HyperSync.requireApiToken
 
   let client = switch FuelHyperSyncClient.make(
     {url: endpointUrl, apiToken},
@@ -213,15 +209,11 @@ Learn more or get a free Envio API token at: https://envio.dev/app/api-tokens`)
     getHeightOrThrow: async () => {
       let timerRef = Performance.now()
       let height = try await client->FuelHyperSyncClient.getHeight catch {
-      | JsExn(e) =>
-        switch e->JsExn.message {
-        | Some(message) if message->isUnauthorizedError =>
-          Logging.error(`Your ENVIO_API_TOKEN was rejected by HyperFuel (401 Unauthorized). The indexer will not be able to fetch events. Update the token and try again using 'envio start' or 'envio dev'. For more info: https://docs.envio.dev/docs/HyperSync/api-tokens`)
-          // Retrying an unauthorized request can never succeed, so block forever
-          let _ = await Promise.make((_, _) => ())
-          0
-        | _ => throw(JsExn(e))
-        }
+      | exn =>
+        exn->HyperSync.rethrowLoggingUnauthorized(
+          ~warned=unauthorizedWarned,
+          ~product="HyperFuel",
+        )
       }
       let seconds = timerRef->Performance.secondsSince
       {height, requestStats: [{method: "getHeight", seconds}]}

package/src/sources/FuelHyperSyncSource.res.mjs

@@ -4,7 +4,6 @@ import * as Source from "./Source.res.mjs";
 import * as Logging from "../Logging.res.mjs";
 import * as HyperSync from "./HyperSync.res.mjs";
 import * as Performance from "../bindings/Performance.res.mjs";
-import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
 import * as ErrorHandling from "../ErrorHandling.res.mjs";
 import * as FuelHyperSync from "./FuelHyperSync.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
@@ -12,22 +11,18 @@ import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as FuelHyperSyncClient from "./FuelHyperSyncClient.res.mjs";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 
-function isUnauthorizedError(message) {
-  return message.includes("401 Unauthorized");
-}
-
 function make(param) {
   let onEventRegistrations = param.onEventRegistrations;
-  let apiToken = param.apiToken;
   let chainId = param.chainId;
-  let apiToken$1 = apiToken !== undefined ? apiToken : Stdlib_JsError.throwWithMessage(`An Envio API token is required for using HyperFuel as a data-source.
-Set the ENVIO_API_TOKEN environment variable in your .env file.
-Learn more or get a free Envio API token at: https://envio.dev/app/api-tokens`);
+  let unauthorizedWarned = {
+    contents: false
+  };
+  let apiToken = HyperSync.requireApiToken(param.apiToken);
   let client;
   try {
     client = FuelHyperSyncClient.make({
       url: param.endpointUrl,
-      apiToken: apiToken$1
+      apiToken: apiToken
     }, FuelHyperSyncClient.Registration.fromOnEventRegistrations(onEventRegistrations), param.addressStore);
   } catch (raw_exn) {
     let exn = Primitive_exceptions.internalToException(raw_exn);
@@ -188,33 +183,9 @@ Learn more or get a free Envio API token at: https://envio.dev/app/api-tokens`);
       let height;
       try {
         height = await client.getHeight();
-      } catch (raw_e) {
-        let e = Primitive_exceptions.internalToException(raw_e);
-        if (e.RE_EXN_ID === "JsExn") {
-          let e$1 = e._1;
-          let message = Stdlib_JsExn.message(e$1);
-          if (message !== undefined) {
-            if (message.includes("401 Unauthorized")) {
-              Logging.error(`Your ENVIO_API_TOKEN was rejected by HyperFuel (401 Unauthorized). The indexer will not be able to fetch events. Update the token and try again using 'envio start' or 'envio dev'. For more info: https://docs.envio.dev/docs/HyperSync/api-tokens`);
-              await new Promise((param, param$1) => {});
-              height = 0;
-            } else {
-              throw {
-                RE_EXN_ID: "JsExn",
-                _1: e$1,
-                Error: new Error()
-              };
-            }
-          } else {
-            throw {
-              RE_EXN_ID: "JsExn",
-              _1: e$1,
-              Error: new Error()
-            };
-          }
-        } else {
-          throw e;
-        }
+      } catch (raw_exn) {
+        let exn = Primitive_exceptions.internalToException(raw_exn);
+        height = HyperSync.rethrowLoggingUnauthorized(exn, unauthorizedWarned, "HyperFuel");
       }
       let seconds = Performance.secondsSince(timerRef);
       return {
@@ -230,7 +201,6 @@ Learn more or get a free Envio API token at: https://envio.dev/app/api-tokens`);
 }
 
 export {
-  isUnauthorizedError,
   make,
 }
 /* Source Not a pure module */

package/src/sources/HyperSync.res

@@ -9,6 +9,37 @@ let pollingInterval = 400
 let rateLimitedPrefix = "RATE_LIMITED:"
 let behindHeadPrefix = "SOURCE_BEHIND_HEAD:"
 
+let requireApiToken = apiToken =>
+  switch apiToken {
+  | Some(token) => token
+  | None =>
+    JsError.throwWithMessage(`An Envio API token is required for using HyperSync as a data-source.
+Set the ENVIO_API_TOKEN environment variable in your .env file.
+Learn more or get a free Envio API token at: https://envio.dev/app/api-tokens`)
+  }
+
+let isUnauthorizedError = (message: string) => message->String.includes("401 Unauthorized")
+
+// Never swallows the failure: the caller's retry ramp has to keep asking,
+// because a token can be replaced without restarting the indexer. All this adds
+// is one loud line the first time a source sees a 401 - saying it on every retry
+// would bury everything else in the log.
+let rethrowLoggingUnauthorized = (exn: exn, ~warned: ref<bool>, ~product: string): 'a => {
+  switch exn {
+  | JsExn(jsExn) =>
+    switch jsExn->JsExn.message {
+    | Some(message) if message->isUnauthorizedError =>
+      if !warned.contents {
+        warned := true
+        Logging.error(`Your ENVIO_API_TOKEN was rejected by ${product} (401 Unauthorized). The indexer will not be able to fetch events. Update the token and try again using 'envio start' or 'envio dev'. For more info: https://docs.envio.dev/docs/HyperSync/api-tokens`)
+      }
+    | _ => ()
+    }
+  | _ => ()
+  }
+  throw(exn)
+}
+
 let markerValue = (msg, ~prefix) =>
   msg->String.slice(~start=prefix->String.length, ~end=msg->String.length)->Int.fromString
 

package/src/sources/HyperSync.res.mjs

@@ -1,17 +1,45 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Source from "./Source.res.mjs";
+import * as Logging from "../Logging.res.mjs";
 import * as Stdlib_Int from "@rescript/runtime/lib/es6/Stdlib_Int.js";
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.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";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 
 let rateLimitedPrefix = "RATE_LIMITED:";
 
 let behindHeadPrefix = "SOURCE_BEHIND_HEAD:";
 
+function requireApiToken(apiToken) {
+  if (apiToken !== undefined) {
+    return Primitive_option.valFromOption(apiToken);
+  } else {
+    return Stdlib_JsError.throwWithMessage(`An Envio API token is required for using HyperSync as a data-source.
+Set the ENVIO_API_TOKEN environment variable in your .env file.
+Learn more or get a free Envio API token at: https://envio.dev/app/api-tokens`);
+  }
+}
+
+function isUnauthorizedError(message) {
+  return message.includes("401 Unauthorized");
+}
+
+function rethrowLoggingUnauthorized(exn, warned, product) {
+  if (exn.RE_EXN_ID === "JsExn") {
+    let message = Stdlib_JsExn.message(exn._1);
+    if (message !== undefined && message.includes("401 Unauthorized") && !warned.contents) {
+      warned.contents = true;
+      Logging.error(`Your ENVIO_API_TOKEN was rejected by ` + product + ` (401 Unauthorized). The indexer will not be able to fetch events. Update the token and try again using 'envio start' or 'envio dev'. For more info: https://docs.envio.dev/docs/HyperSync/api-tokens`);
+    }
+  }
+  throw exn;
+}
+
 function markerValue(msg, prefix) {
   return Stdlib_Int.fromString(msg.slice(prefix.length, msg.length), undefined);
 }
@@ -163,6 +191,9 @@ let pollingInterval = 400;
 
 export {
   pollingInterval,
+  requireApiToken,
+  isUnauthorizedError,
+  rethrowLoggingUnauthorized,
   mapNativeFailure,
   mapNativeFailureExn,
   reraiseIfRecoverable,

package/src/sources/HyperSync.resi

@@ -10,6 +10,22 @@ type logsQueryPage = {
 // one. Every ecosystem's client talks to the same service, so they wait alike.
 let pollingInterval: int
 
+// Every HyperSync-backed source needs a token to reach the service, so a
+// missing one fails at construction with the message that says how to get one,
+// rather than as a 401 per request.
+let requireApiToken: option<string> => string
+
+// Surfaced by the native clients when the edge rejects the API token. The
+// corrupted-token test feeds the real server error (from the query endpoint;
+// the edge no longer 401s malformed tokens on /height) through this so it can't
+// silently drift away from the message shape a 401 actually produces.
+let isUnauthorizedError: string => bool
+
+// Rethrows every failure unchanged, adding one loud line the first time a source
+// sees a 401. Never swallows it: the caller's retry ramp has to keep asking,
+// because a token can be replaced without restarting the indexer.
+let rethrowLoggingUnauthorized: (exn, ~warned: ref<bool>, ~product: string) => 'a
+
 // Map a native client's `PREFIX:<int>` failure marker onto the exception
 // SourceManager retries on (`RateLimited` / `SourceBehindHead`), falling back to
 // the original cause.