envio 3.5.1 → 3.6.1-subgraph

package/src/Config.res.mjs

@@ -22,6 +22,16 @@ import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
 import * as EventConfigBuilder from "./EventConfigBuilder.res.mjs";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 
+let chainIdFieldName = "chainId";
+
+function chainIdColumnName(format) {
+  if (format === "original") {
+    return chainIdFieldName;
+  } else {
+    return "chain_id";
+  }
+}
+
 let name = "envio_addresses";
 
 function makeId(chainId, address) {
@@ -42,11 +52,11 @@ let schema = S$RescriptSchema.schema(s => ({
 }));
 
 let table = Table.mkTable(name, undefined, [
-  Table.mkField("id", "String", S$RescriptSchema.string, undefined, undefined, undefined, true, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("chain_id", "ChainId", ChainId.schema, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("registration_block", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("registration_log_index", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("contract_name", "String", S$RescriptSchema.string, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined)
+  Table.mkField("id", "String", S$RescriptSchema.string, undefined, undefined, undefined, true, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("chain_id", "ChainId", ChainId.schema, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("registration_block", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("registration_log_index", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("contract_name", "String", S$RescriptSchema.string, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined)
 ], undefined);
 
 let entityConfig_storage = {
@@ -59,7 +69,8 @@ let entityConfig = {
   index: -1,
   schema: schema,
   table: table,
-  storage: entityConfig_storage
+  storage: entityConfig_storage,
+  crossChain: true
 };
 
 let EnvioAddresses = {
@@ -217,6 +228,7 @@ let entityStorageSchema = S$RescriptSchema.schema(s => ({
 
 let entityJsonSchema = S$RescriptSchema.schema(s => ({
   name: s.m(S$RescriptSchema.string),
+  crossChain: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   storage: s.m(S$RescriptSchema.option(entityStorageSchema)),
   properties: s.m(S$RescriptSchema.array(propertySchema)),
   derivedFields: s.m(S$RescriptSchema.option(S$RescriptSchema.array(derivedFieldSchema))),
@@ -324,19 +336,24 @@ function parseEnumsFromJson(enumsJson) {
   return Object.entries(enumsJson).map(param => Table.makeEnumConfig(param[0], param[1]));
 }
 
-function parseEntitiesFromJson(entitiesJson, enumConfigsByName, globalStorage) {
+function makeChainIdField(globalStorage) {
+  return Table.mkField(chainIdFieldName, "ChainId", ChainId.schema, undefined, undefined, undefined, true, undefined, true, undefined, undefined, chainIdColumnName(globalStorage.postgresColumnNameFormat), chainIdColumnName(globalStorage.clickhouseColumnNameFormat));
+}
+
+function parseEntitiesFromJson(entitiesJson, enumConfigsByName, globalStorage, defaultCrossChain) {
   return entitiesJson.map((entityJson, index) => {
     let entityName = entityJson.name;
+    let crossChain = Stdlib_Option.getOr(entityJson.crossChain, defaultCrossChain);
     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, prop.description, prop.postgresDbName, prop.clickhouseDbName);
+      return Table.mkField(prop.name, match[0], match[1], undefined, match[3], match[2], prop.name === "id", match[4], undefined, prop.linkedEntity, prop.description, prop.postgresDbName, prop.clickhouseDbName);
     });
     let derivedFields = Stdlib_Option.getOr(entityJson.derivedFields, []).map(df => Table.mkDerivedFromField(df.fieldName, df.derivedFromEntity, df.derivedFromField, df.description));
     let compositeIndexes = Stdlib_Option.getOr(entityJson.compositeIndices, []).map(ci => ci.map(f => ({
       fieldName: f.fieldName,
       direction: f.direction === "Asc" ? "Asc" : "Desc"
     })));
-    let table = Table.mkTable(entityName, compositeIndexes, fields.concat(derivedFields), entityJson.description);
+    let table = Table.mkTable(entityName, compositeIndexes, fields.concat(crossChain ? [] : [makeChainIdField(globalStorage)], derivedFields), entityJson.description);
     let getApiFieldName = prop => {
       let match = prop.linkedEntity;
       if (match !== undefined) {
@@ -382,14 +399,22 @@ function parseEntitiesFromJson(entitiesJson, enumConfigsByName, globalStorage) {
       index: index,
       schema: schema,
       table: table,
-      storage: storage
+      storage: storage,
+      crossChain: crossChain
     };
   });
 }
 
+let columnNameFormatSchema = S$RescriptSchema.$$enum([
+  "original",
+  "snake_case"
+]);
+
 let publicConfigStorageSchema = S$RescriptSchema.schema(s => ({
   postgres: s.m(S$RescriptSchema.bool),
-  clickhouse: s.m(S$RescriptSchema.option(S$RescriptSchema.bool))
+  clickhouse: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
+  postgresColumnNameFormat: s.m(S$RescriptSchema.option(columnNameFormatSchema)),
+  clickhouseColumnNameFormat: s.m(S$RescriptSchema.option(columnNameFormatSchema))
 }));
 
 let publicConfigSchema = S$RescriptSchema.schema(s => ({
@@ -402,12 +427,14 @@ let publicConfigSchema = S$RescriptSchema.schema(s => ({
   saveFullHistory: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   rawEvents: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   chainIdMode: s.m(S$RescriptSchema.option(ChainId.modeSchema)),
+  defaultCrossChain: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   storage: s.m(publicConfigStorageSchema),
   evm: s.m(S$RescriptSchema.option(publicConfigEvmSchema)),
   fuel: s.m(S$RescriptSchema.option(publicConfigEcosystemSchema)),
   svm: s.m(S$RescriptSchema.option(publicConfigEcosystemSchema)),
   enums: s.m(S$RescriptSchema.option(S$RescriptSchema.dict(S$RescriptSchema.array(S$RescriptSchema.string)))),
-  entities: s.m(S$RescriptSchema.option(S$RescriptSchema.array(entityJsonSchema)))
+  entities: s.m(S$RescriptSchema.option(S$RescriptSchema.array(entityJsonSchema))),
+  subgraph: s.m(S$RescriptSchema.option(S$RescriptSchema.json(false)))
 }));
 
 function fromPublic(publicConfigJson) {
@@ -689,11 +716,16 @@ function fromPublic(publicConfigJson) {
   ]));
   let globalStorage_postgres = publicConfig.storage.postgres;
   let globalStorage_clickhouse = Stdlib_Option.getOr(publicConfig.storage.clickhouse, false);
+  let globalStorage_postgresColumnNameFormat = Stdlib_Option.getOr(publicConfig.storage.postgresColumnNameFormat, "original");
+  let globalStorage_clickhouseColumnNameFormat = Stdlib_Option.getOr(publicConfig.storage.clickhouseColumnNameFormat, "original");
   let globalStorage = {
     postgres: globalStorage_postgres,
-    clickhouse: globalStorage_clickhouse
+    clickhouse: globalStorage_clickhouse,
+    postgresColumnNameFormat: globalStorage_postgresColumnNameFormat,
+    clickhouseColumnNameFormat: globalStorage_clickhouseColumnNameFormat
   };
-  let userEntities = parseEntitiesFromJson(Stdlib_Option.getOr(publicConfig.entities, []), enumConfigsByName, globalStorage);
+  let defaultCrossChain = Stdlib_Option.getOr(publicConfig.defaultCrossChain, true);
+  let userEntities = parseEntitiesFromJson(Stdlib_Option.getOr(publicConfig.entities, []), enumConfigsByName, globalStorage, defaultCrossChain);
   let allEntities = userEntities.concat([entityConfig]);
   let userEntitiesByName = Object.fromEntries(userEntities.map(entityConfig => [
     Utils.$$String.capitalize(entityConfig.name),
@@ -710,6 +742,7 @@ function fromPublic(publicConfigJson) {
     contractHandlers: contractHandlers,
     shouldRollbackOnReorg: Stdlib_Option.getOr(publicConfig.rollbackOnReorg, true),
     shouldSaveFullHistory: Stdlib_Option.getOr(publicConfig.saveFullHistory, false),
+    defaultCrossChain: defaultCrossChain,
     storage: globalStorage,
     chainIdMode: Stdlib_Option.getOr(publicConfig.chainIdMode, "int32"),
     chainMap: chainMap,
@@ -725,7 +758,8 @@ function fromPublic(publicConfigJson) {
     userEntitiesByName: userEntitiesByName,
     userEntities: userEntities,
     allEntities: allEntities,
-    allEnums: allEnums
+    allEnums: allEnums,
+    subgraph: publicConfig.subgraph
   };
 }
 
@@ -870,6 +904,10 @@ function stripSensitiveData(json) {
     stripChains(cloned["evm"]);
     stripChains(cloned["fuel"]);
     stripChains(cloned["svm"]);
+    let match = cloned["subgraph"];
+    if (typeof match === "object" && match !== null && !Array.isArray(match)) {
+      Utils.Dict.deleteInPlace(match, "rpcUrls");
+    }
   }
   return cloned;
 }
@@ -1049,6 +1087,8 @@ function getPgUserEntities(config) {
 }
 
 export {
+  chainIdFieldName,
+  chainIdColumnName,
   EnvioAddresses,
   rpcSourceForSchema,
   rpcConfigSchema,
@@ -1069,7 +1109,9 @@ export {
   entityJsonSchema,
   getFieldTypeAndSchema,
   parseEnumsFromJson,
+  makeChainIdField,
   parseEntitiesFromJson,
+  columnNameFormatSchema,
   publicConfigStorageSchema,
   publicConfigSchema,
   fromPublic,

package/src/Core.res

@@ -24,8 +24,16 @@ type fromUserApiResult = {
   indexerCode: Null.t<string>,
 }
 
+type fromSubgraphOptions = {
+  name?: string,
+  env?: dict<string>,
+  files?: dict<string>,
+  root?: string,
+}
+
 type addon = {
   getConfigJson: (~configPath: Null.t<string>, ~directory: Null.t<string>) => string,
+  fromSubgraph: (string, string, fromSubgraphOptions) => fromUserApiResult,
   encodeIndexedTopic: (~abiType: string, ~value: unknown) => EvmTypes.Hex.t,
   fromUserApi: (string, fromUserApiOptions) => fromUserApiResult,
   runCli: (~args: array<string>, ~envioPackageDir: Null.t<string>) => promise<Null.t<string>>,
@@ -232,6 +240,13 @@ let fromUserApi = (~schema=?, ~env=?, ~files=?, ~withIndexerTypes=false, yaml) =
   )
 }
 
+/// Parses a subgraph project without touching the filesystem: subgraph.yaml and
+/// its schema inline, ABI bodies through `files`.
+let fromSubgraph = (~name=?, ~env=?, ~files=?, ~root=?, ~manifest, ~schema) => {
+  let addon = getAddon()
+  addon.fromSubgraph(manifest, schema, {?name, ?env, ?files, ?root})
+}
+
 let runCli = args => {
   let addon = getAddon()
   addon.runCli(~args, ~envioPackageDir=Null.make(envioPackageDir))

package/src/Core.res.mjs

@@ -191,6 +191,16 @@ function fromUserApi(schema, env, files, withIndexerTypesOpt, yaml) {
   });
 }
 
+function fromSubgraph(name, env, files, root, manifest, schema) {
+  let addon = getAddon();
+  return addon.fromSubgraph(manifest, schema, {
+    name: name,
+    env: env,
+    files: files,
+    root: root
+  });
+}
+
 function runCli(args) {
   let addon = getAddon();
   return addon.runCli(args, envioPackageDir);
@@ -208,6 +218,7 @@ export {
   getAddon,
   getConfigJson,
   fromUserApi,
+  fromSubgraph,
   runCli,
 }
 /* envioPackageDir Not a pure module */

package/src/EffectState.res

@@ -131,7 +131,7 @@ let commitCacheCount = (inMemTable: effectCacheInMemTable, ~count) => {
 
 let statsToMetrics = (stats: effectStats): Metrics.effectMetrics => {
   Metrics.effect: stats.effectName,
-  scope: stats.scope->Internal.EffectCache.scopeToString,
+  scope: stats.scope->Internal.chainScopeToString,
   callSeconds: stats.callSeconds,
   callSecondsTotal: stats.callSecondsTotal,
   callCount: stats.callCount,
@@ -152,7 +152,7 @@ let toMetrics = (self: t): array<Metrics.effectMetrics> => {
     metrics
     ->Array.push({
       Metrics.effect: effectName,
-      scope: scope->Internal.EffectCache.scopeToString,
+      scope: scope->Internal.chainScopeToString,
       callSeconds: 0.,
       callSecondsTotal: 0.,
       callCount: 0.,

package/src/EffectState.res.mjs

@@ -68,7 +68,7 @@ function toMetrics(self) {
     let stats = t.stats;
     return {
       effect: stats.effectName,
-      scope: Internal.EffectCache.scopeToString(stats.scope),
+      scope: Internal.chainScopeToString(stats.scope),
       callSeconds: stats.callSeconds,
       callSecondsTotal: stats.callSecondsTotal,
       callCount: stats.callCount,
@@ -82,7 +82,7 @@ function toMetrics(self) {
   Utils.Dict.forEach(self.unregisteredCacheCounts, param => {
     metrics.push({
       effect: param.effectName,
-      scope: Internal.EffectCache.scopeToString(param.scope),
+      scope: Internal.chainScopeToString(param.scope),
       callSeconds: 0,
       callSecondsTotal: 0,
       callCount: 0,

package/src/EntityTables.res

@@ -0,0 +1,32 @@
+// One in-memory table per entity, for a single chain scope. The indexer holds
+// the cross-chain partition; each ChainState holds the per-chain one.
+
+type t = dict<InMemoryTable.Entity.t>
+
+exception UndefinedEntity({entityName: string})
+
+let make = (entities: array<Internal.entityConfig>): t => {
+  let init = Dict.make()
+  entities->Array.forEach(entityConfig => {
+    init->Dict.set((entityConfig.name :> string), InMemoryTable.Entity.make())
+  })
+  init
+}
+
+let get = (self: t, ~entityName: string) => {
+  switch self->Utils.Dict.dangerouslyGetNonOption(entityName) {
+  | Some(table) => table
+  | None =>
+    UndefinedEntity({entityName: entityName})->ErrorHandling.mkLogAndRaise(
+      ~msg="Unexpected, entity InMemoryTable is undefined",
+    )
+  }
+}
+
+// Entities whose rows are shared by every chain, so their tables live on the
+// indexer rather than on a ChainState.
+let crossChain = (entities: array<Internal.entityConfig>) =>
+  entities->Array.filter((entityConfig: Internal.entityConfig) => entityConfig.crossChain)
+
+let perChain = (entities: array<Internal.entityConfig>) =>
+  entities->Array.filter((entityConfig: Internal.entityConfig) => !entityConfig.crossChain)

package/src/EntityTables.res.mjs

@@ -0,0 +1,44 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as ErrorHandling from "./ErrorHandling.res.mjs";
+import * as InMemoryTable from "./InMemoryTable.res.mjs";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+
+let UndefinedEntity = /* @__PURE__ */Primitive_exceptions.create("EntityTables.UndefinedEntity");
+
+function make(entities) {
+  let init = {};
+  entities.forEach(entityConfig => {
+    init[entityConfig.name] = InMemoryTable.Entity.make();
+  });
+  return init;
+}
+
+function get(self, entityName) {
+  let table = self[entityName];
+  if (table !== undefined) {
+    return table;
+  } else {
+    return ErrorHandling.mkLogAndRaise(undefined, "Unexpected, entity InMemoryTable is undefined", {
+      RE_EXN_ID: UndefinedEntity,
+      entityName: entityName
+    });
+  }
+}
+
+function crossChain(entities) {
+  return entities.filter(entityConfig => entityConfig.crossChain);
+}
+
+function perChain(entities) {
+  return entities.filter(entityConfig => !entityConfig.crossChain);
+}
+
+export {
+  UndefinedEntity,
+  make,
+  get,
+  crossChain,
+  perChain,
+}
+/* ErrorHandling Not a pure module */

package/src/Envio.res

@@ -186,7 +186,8 @@ and effectOptions<'input, 'output> = {
   rateLimit: rateLimit,
   /** Whether the effect should be cached. */
   cache?: bool,
-  /** Whether the effect's cache is shared across all chains. Defaults to `true`.
+  /** Whether the effect's cache is shared across all chains. Defaults to `true`,
+   or to `false` when config.yaml sets `disable_default_cross_chain: true`.
    Set to `false` to isolate the cache (and rate limiting) per chain and enable
    `context.chain.id` inside the handler. */
   crossChain?: bool,
@@ -196,8 +197,8 @@ and effectContext = {
   log: logger,
   effect: 'input 'output. (effect<'input, 'output>, 'input) => promise<'output>,
   mutable cache: bool,
-  /** The chain the effect was called on. Only available on effects created with
-   `crossChain: false`; accessing it on a cross-chain effect throws. */
+  /** The chain the effect was called on. Only available on chain-scoped
+   effects; accessing it on a cross-chain effect throws. */
   chain: effectChain,
 }
 and effectArgs<'input> = {
@@ -259,10 +260,9 @@ let createEffect = (
     | Some(true) => true
     | _ => false
     },
-    crossChain: switch options.crossChain {
-    | Some(false) => false
-    | _ => true
-    },
+    // Left unresolved: the config's `defaultCrossChain` fills it in when the
+    // effect didn't state one, and the config isn't available here.
+    crossChain: options.crossChain,
     rateLimit: switch options.rateLimit {
     | Disable => None
     | Enable({calls, per}) =>

package/src/Envio.res.mjs

@@ -30,12 +30,11 @@ function createEffect(options, handler) {
     output: s.m(outputSchema)
   }));
   let match = options.cache;
-  let match$1 = options.crossChain;
-  let match$2 = options.rateLimit;
+  let match$1 = options.rateLimit;
   let tmp;
-  tmp = match$2 === false ? undefined : ({
-      callsPerDuration: match$2.calls,
-      durationMs: durationToMs(match$2.per)
+  tmp = match$1 === false ? undefined : ({
+      callsPerDuration: match$1.calls,
+      durationMs: durationToMs(match$1.per)
     });
   return {
     name: options.name,
@@ -45,7 +44,7 @@ function createEffect(options, handler) {
       outputSchema: outputSchema
     },
     defaultShouldCache: match !== undefined ? match : false,
-    crossChain: match$1 !== undefined ? match$1 : true,
+    crossChain: options.crossChain,
     output: outputSchema,
     input: S$RescriptSchema.schema(param => options.input),
     rateLimit: tmp

package/src/EventProcessing.res

@@ -51,7 +51,7 @@ let runEventHandlerOrThrow = async (
       isPreload: false,
       chains,
       config,
-      isResolved: false,
+      sync: UserContext.makeSyncState(),
     }
     await handler(
       (
@@ -61,7 +61,7 @@ let runEventHandlerOrThrow = async (
         }: Internal.handlerArgs
       ),
     )
-    contextParams.isResolved = true
+    contextParams.sync.status = Resolved
   } catch {
   | exn =>
     throw(
@@ -102,7 +102,7 @@ let runHandlerOrThrow = async (
         isPreload: false,
         chains,
         config,
-        isResolved: false,
+        sync: UserContext.makeSyncState(),
       }
       await handler(
         Ecosystem.makeOnBlockArgs(
@@ -111,7 +111,7 @@ let runHandlerOrThrow = async (
           ~context=UserContext.getHandlerContext(contextParams),
         ),
       )
-      contextParams.isResolved = true
+      contextParams.sync.status = Resolved
     } catch {
     | exn =>
       throw(
@@ -186,7 +186,7 @@ let preloadBatchOrThrow = async (
                   checkpointId,
                   isPreload: true,
                   chains,
-                  isResolved: false,
+                  sync: UserContext.makeSyncState(),
                   config,
                 }),
               })
@@ -221,7 +221,7 @@ let preloadBatchOrThrow = async (
                   checkpointId,
                   isPreload: true,
                   chains,
-                  isResolved: false,
+                  sync: UserContext.makeSyncState(),
                   config,
                 }),
               )

package/src/EventProcessing.res.mjs

@@ -38,6 +38,7 @@ let ProcessingError = /* @__PURE__ */Primitive_exceptions.create("EventProcessin
 async function runEventHandlerOrThrow(item, checkpointId, handler, indexerState, loadManager, persistence, chains, config) {
   let timeBeforeHandler = Performance.now();
   try {
+    let contextParams_sync = UserContext.makeSyncState();
     let contextParams = {
       item: item,
       checkpointId: checkpointId,
@@ -47,13 +48,13 @@ async function runEventHandlerOrThrow(item, checkpointId, handler, indexerState,
       isPreload: false,
       chains: chains,
       config: config,
-      isResolved: false
+      sync: contextParams_sync
     };
     await handler({
       event: Ecosystem.getItemEvent(item, config.ecosystem),
       context: UserContext.getHandlerContext(contextParams)
     });
-    contextParams.isResolved = true;
+    contextParams_sync.status = "Resolved";
   } catch (raw_exn) {
     let exn = Primitive_exceptions.internalToException(raw_exn);
     throw {
@@ -79,6 +80,7 @@ async function runHandlerOrThrow(item, checkpointId, indexerState, loadManager,
     }
   }
   try {
+    let contextParams_sync = UserContext.makeSyncState();
     let contextParams = {
       item: item,
       checkpointId: checkpointId,
@@ -88,10 +90,10 @@ async function runHandlerOrThrow(item, checkpointId, indexerState, loadManager,
       isPreload: false,
       chains: chains,
       config: config,
-      isResolved: false
+      sync: contextParams_sync
     };
     await item.onBlockRegistration.handler(Ecosystem.makeOnBlockArgs(item.blockNumber, config.ecosystem, UserContext.getHandlerContext(contextParams)));
-    contextParams.isResolved = true;
+    contextParams_sync.status = "Resolved";
     return;
   } catch (raw_exn) {
     let exn = Primitive_exceptions.internalToException(raw_exn);
@@ -133,7 +135,7 @@ async function preloadBatchOrThrow(batch, loadManager, persistence, config, inde
                 isPreload: true,
                 chains: chains,
                 config: config,
-                isResolved: false
+                sync: UserContext.makeSyncState()
               })
             }).then(() => IndexerState.endPreloadHandler(indexerState, timerRef, contractName, eventName))));
           } catch (exn) {
@@ -151,7 +153,7 @@ async function preloadBatchOrThrow(batch, loadManager, persistence, config, inde
             isPreload: true,
             chains: chains,
             config: config,
-            isResolved: false
+            sync: UserContext.makeSyncState()
           })))));
         } catch (exn$1) {
           

package/src/HandlerLoader.res

@@ -77,18 +77,30 @@ let autoLoadFromSrcHandlers = async (~handlers: string) => {
 // `HandlerRegister.finishRegistration`. This loads the user handler files
 // (populating the global `HandlerRegister` registry as a side effect) and
 // returns the resulting per-chain registrations.
+// The subgraph runtime lives in this package but is never exported: it's
+// reached only from here, when the resolved config carries a translated
+// manifest.
+let registerSubgraph: (JSON.t, ~isDev: bool) => promise<unit> = %raw(`(subgraph, isDev) =>
+  import("./subgraph/runtime.ts").then((m) => m.registerSubgraph({ ...subgraph, isDev }))`)
+
 let registerAllHandlers = async (~config: Config.t): HandlerRegister.registrationsByChainId => {
   HandlerRegister.startRegistration(~config)
 
-  // Auto-load all .js files from src/handlers directory
-  await autoLoadFromSrcHandlers(~handlers=config.handlers)
+  switch config.subgraph {
+  // A subgraph project's `src/` holds AssemblyScript mappings, not envio
+  // handlers, so the usual auto-load would import them without a scope.
+  | Some(subgraph) => await registerSubgraph(subgraph, ~isDev=config.isDev)
+  | None =>
+    // Auto-load all .js files from src/handlers directory
+    await autoLoadFromSrcHandlers(~handlers=config.handlers)
 
-  // Load contract-specific handlers
-  let _ = await config.contractHandlers
-  ->Array.map(({name, handler}) => {
-    registerContractHandlers(~contractName=name, ~handler)
-  })
-  ->Promise.all
+    // Load contract-specific handlers
+    let _ = await config.contractHandlers
+    ->Array.map(({name, handler}) => {
+      registerContractHandlers(~contractName=name, ~handler)
+    })
+    ->Promise.all
+  }
 
   HandlerRegister.finishRegistration(~config)
 }

package/src/HandlerLoader.res.mjs

@@ -56,10 +56,18 @@ async function autoLoadFromSrcHandlers(handlers) {
   })));
 }
 
+let registerSubgraph = ((subgraph, isDev) =>
+  import("./subgraph/runtime.ts").then((m) => m.registerSubgraph({ ...subgraph, isDev })));
+
 async function registerAllHandlers(config) {
   HandlerRegister.startRegistration(config);
-  await autoLoadFromSrcHandlers(config.handlers);
-  await Promise.all(config.contractHandlers.map(param => registerContractHandlers(param.name, param.handler)));
+  let subgraph = config.subgraph;
+  if (subgraph !== undefined) {
+    await registerSubgraph(subgraph, config.isDev);
+  } else {
+    await autoLoadFromSrcHandlers(config.handlers);
+    await Promise.all(config.contractHandlers.map(param => registerContractHandlers(param.name, param.handler)));
+  }
   return HandlerRegister.finishRegistration(config);
 }
 
@@ -67,6 +75,7 @@ export {
   toImportUrl,
   registerContractHandlers,
   autoLoadFromSrcHandlers,
+  registerSubgraph,
   registerAllHandlers,
 }
 /*  Not a pure module */