envio 3.14.0-subgraph → 3.14.1-resolvers.2

package/evm.schema.json

@@ -29,6 +29,13 @@
         "null"
       ]
     },
+    "resolvers": {
+      "description": "Optional relative path to the custom GraphQL resolvers, either a single module (e.g. 'src/Resolvers.ts') or a directory (e.g. 'src/resolvers'), in which case every .js/.mjs/.ts file beneath it is loaded, tests excluded. The resolvers they export are served as additional root fields on the indexer's GraphQL endpoint.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
     "full_batch_size": {
       "description": "Target number of events to be processed per batch. Set it to smaller number if you have many Effect API calls which are slow to resolve and can't be batched. (Default: 5000)",
       "type": [
@@ -543,7 +550,7 @@
       "type": "object",
       "properties": {
         "url": {
-          "description": "The RPC endpoint URL.",
+          "description": "The RPC endpoint URL. An entry whose url is empty, for example `${RPC_URL:-}` with the variable unset, is ignored.",
           "type": "string"
         },
         "for": {

package/fuel.schema.json

@@ -29,6 +29,13 @@
         "null"
       ]
     },
+    "resolvers": {
+      "description": "Optional relative path to the custom GraphQL resolvers, either a single module (e.g. 'src/Resolvers.ts') or a directory (e.g. 'src/resolvers'), in which case every .js/.mjs/.ts file beneath it is loaded, tests excluded. The resolvers they export are served as additional root fields on the indexer's GraphQL endpoint.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
     "full_batch_size": {
       "description": "Target number of events to be processed per batch. Set it to smaller number if you have many Effect API calls which are slow to resolve and can't be batched. (Default: 5000)",
       "type": [

package/index.d.ts

@@ -2027,10 +2027,10 @@ type ConfigEntities<Config extends IndexerConfigTypes = GlobalConfig> =
 type PerChainEntityNames<Config extends IndexerConfigTypes = GlobalConfig> =
   Config extends { perChainEntities: infer Names extends string } ? Names : never;
 
-/** The row shape the chain-agnostic test-indexer operations exchange. A
- * per-chain entity's row is only identified together with its chain, so the
- * chain id travels alongside the entity fields. */
-type TestIndexerEntityRow<
+/** The row shape chain-agnostic APIs exchange. A per-chain entity's row is
+ * only identified together with its chain, so the chain id travels alongside
+ * the entity fields. */
+type ChainScopedEntityRow<
   Config extends IndexerConfigTypes,
   Name,
   Entity
@@ -2224,7 +2224,7 @@ export type TestIndexerFromConfig<Config extends IndexerConfigTypes = GlobalConf
 } & SingleEcosystemTestChains<Config> & {
   /** Entity operations for direct manipulation outside of handlers. */
   readonly [K in keyof ConfigEntities<Config>]: TestIndexerEntityOperations<
-    TestIndexerEntityRow<Config, K, ConfigEntities<Config>[K]>
+    ChainScopedEntityRow<Config, K, ConfigEntities<Config>[K]>
   >;
 };
 
@@ -2298,6 +2298,259 @@ export type EnumName = keyof EnumsT & string;
 /** Lookup an enum value type by name (e.g. `Enum<"AccountType">`). */
 export type Enum<TName extends EnumName> = EnumsT[TName];
 
+// ============== Custom Resolver Types ==============
+
+/** Handle for a custom GraphQL resolver created via {@link createResolver}. */
+export declare abstract class Resolver<Args, Output> {
+  protected opaque: Args | Output;
+}
+
+/** The selection the caller asked for: field names and their nesting, with
+ *  aliases and fragments already resolved away. A resolver may use it to skip
+ *  work it wasn't asked for — the response is projected against the declared
+ *  schema either way, so correctness never depends on honouring it. */
+export type ResolverSelection = { readonly [field: string]: ResolverSelection };
+
+/** Request metadata, forwarded by envio-serve. */
+export type ResolverContext = {
+  /** The role the operation was executed under. `admin: true` resolvers are
+   *  only reachable as `"admin"`. */
+  readonly role: "public" | "admin";
+  /** Correlates this field's work with the operation it belongs to. */
+  readonly requestId: string;
+  /** W3C trace context of the incoming request, when the caller sent one. */
+  readonly traceparent?: string;
+};
+
+/** How far a chain has been indexed. Read it to refuse to answer from a stale
+ *  index — `sourceBlock - progressBlock` is how far behind the head the
+ *  indexer is. */
+export type ChainHeight = {
+  readonly chainId: number;
+  /** `"evm"`, `"fuel"` or `"svm"`. Chain ids are only unique within one. */
+  readonly ecosystem: string;
+  readonly startBlock: number;
+  readonly endBlock: number | null;
+  /** The latest block seen on the chain. */
+  readonly sourceBlock: number;
+  /** The latest block fetched from the source. */
+  readonly bufferBlock: number;
+  /** The latest block whose events have been processed and committed. */
+  readonly progressBlock: number;
+  /** When the chain first caught up to the head, or null while it hasn't. */
+  readonly readyAt: Date | null;
+  readonly isReady: boolean;
+};
+
+/** Raw SQL, run under the resolver's `statement_timeout` and against its
+ *  bounded pool. */
+export type ResolverSql = {
+  /** ``db.sql`select 1` `` */
+  <Row = Record<string, unknown>>(
+    strings: TemplateStringsArray,
+    ...values: readonly unknown[]
+  ): Promise<Row[]>;
+  /** `db.sql.unsafe(text, params)` — the direct lift for a query built as a
+   *  string with positional parameters. */
+  unsafe<Row = Record<string, unknown>>(
+    text: string,
+    params?: readonly unknown[],
+    options?: { readonly prepare?: boolean }
+  ): Promise<Row[]>;
+};
+
+/** Options accepted by `db.find`. */
+export type ResolverFindOptions<Entity> = {
+  /** Filter by field, with the same operators as `context.<Entity>.getWhere`.
+   *  Unlike `getWhere`, any field can be filtered on here — it is a query
+   *  against the table, so an unindexed field is a slow one, not an error. */
+  readonly where?: GetWhereFilter<Entity>;
+  readonly orderBy?: readonly {
+    readonly field: keyof Entity & string;
+    readonly direction: "asc" | "desc";
+  }[];
+  readonly limit?: number;
+  readonly offset?: number;
+};
+
+/** The database a resolver reads through. Every query it runs carries the
+ *  resolver's `timeoutMs` as a `statement_timeout` and takes one of the
+ *  process's bounded connections. */
+export type ResolverDb<Config extends IndexerConfigTypes = GlobalConfig> = {
+  /** Entities matching `where`, decoded exactly as a handler sees them. */
+  readonly find: <Name extends keyof ConfigEntities<Config> & string>(
+    entityName: Name,
+    options?: ResolverFindOptions<
+      ChainScopedEntityRow<Config, Name, ConfigEntities<Config>[Name]>
+    >
+  ) => Promise<
+    ChainScopedEntityRow<Config, Name, ConfigEntities<Config>[Name]>[]
+  >;
+  /** One entity by id, or null. Not available for per-chain entities, whose
+   *  key is the id together with a chain — use {@link ResolverDb.find}. */
+  readonly get: <
+    Name extends Exclude<
+      keyof ConfigEntities<Config> & string,
+      PerChainEntityNames<Config>
+    >
+  >(
+    entityName: Name,
+    id: EntityId<ConfigEntities<Config>[Name]>
+  ) => Promise<ConfigEntities<Config>[Name] | null>;
+  /** Raw SQL, for what the loaders don't express. */
+  readonly sql: ResolverSql;
+  /** The Postgres schema the indexer's tables live in. Raw SQL has to qualify
+   *  table names with it — it is not `"public"` on a hosted deployment. */
+  readonly pgSchema: string;
+  /** Several queries on one connection, under one timeout. */
+  readonly transaction: <T>(work: (sql: ResolverSql) => Promise<T>) => Promise<T>;
+  /** How far each chain has been indexed, keyed by chain id. */
+  readonly chainHeights: () => Promise<Record<string, ChainHeight>>;
+};
+
+/** Arguments passed to a {@link Resolver}'s handler. */
+export type ResolverHandlerArgs<
+  Args,
+  Config extends IndexerConfigTypes = GlobalConfig
+> = {
+  /** Coerced and validated against the declared arg schemas before the
+   *  resolver is reached. */
+  readonly args: Args;
+  readonly db: ResolverDb<Config>;
+  readonly selection: ResolverSelection;
+  readonly ctx: ResolverContext;
+};
+
+/**
+ * Declares a custom GraphQL resolver: a root query field served alongside the
+ * generated entity fields, backed by TypeScript in this project.
+ *
+ * Arguments and result are declared with the same `S` schemas effects use, and
+ * the GraphQL types are derived from them. A field is non-null unless its
+ * schema is optional. Object types must be named with {@link defineType} —
+ * GraphQL has no anonymous types.
+ *
+ * ```ts
+ * export const marketsAprByPeriod = createResolver({
+ *   name: "marketsAprByPeriod",
+ *   args: { periodStart: S.int32, periodEnd: S.int32 },
+ *   output: S.array(defineType("MarketApr", { marketAddress: S.string })),
+ *   timeoutMs: 30_000,
+ *   handler: async ({ args, db }) => db.find("MarketInfo"),
+ * });
+ * ```
+ */
+export function createResolver<
+  // Both are schemas at runtime: `createResolver` reads `output.t` and walks
+  // every argument with `toGraphQLType` while the module is being imported, so
+  // anything else fails at indexer startup rather than in the editor.
+  AS extends Record<string, Sury.Schema<unknown>>,
+  OS extends Sury.Schema<unknown>,
+  A = UnknownToOutput<AS>,
+  O = UnknownToOutput<OS>,
+  // A hack to enforce that the inferred return type matches the output schema.
+  R extends O = O
+>(options: {
+  /** The GraphQL field name. Must not collide with a generated one. */
+  readonly name: string;
+  /** Shown in the schema, for the people querying it. */
+  readonly description?: string;
+  /** Argument schemas, keyed by argument name. */
+  readonly args?: AS;
+  /** The result schema. Determines the field's GraphQL type. */
+  readonly output: OS;
+  /** Refuse the field to callers who cannot present a key from
+   *  `ENVIO_RESOLVERS_PRIVATE_KEYS` in the `x-envio-private-key` header. With
+   *  no keys configured it refuses everyone.
+   *
+   *  This hides the answers, not the field: Hasura will not route to an action
+   *  it does not publish, so a private resolver is on the public schema and its
+   *  name, arguments and result type stay visible to anonymous introspection.
+   *  A name that would itself disclose something does not belong here. */
+  readonly private?: boolean;
+  /** @deprecated The former spelling of `private`, and identical to it. */
+  readonly admin?: boolean;
+  /** Refuse to answer with a 503 when the index is further behind head than
+   *  this. A number applies to every chain; an object of chainId to blocks
+   *  applies per chain and ignores the chains it does not name — which is
+   *  usually what you want, since a few hundred blocks is seconds on one chain
+   *  and hours on another. Omitted, the resolver answers whatever the index
+   *  currently holds. */
+  readonly maxBlocksBehind?: number | Readonly<Record<number, number>>;
+  /** The `statement_timeout` every query this resolver runs is bounded by.
+   *  Required: it is the only thing bounding a runaway query. */
+  readonly timeoutMs: number;
+  readonly handler: (args: ResolverHandlerArgs<A>) => Promise<R>;
+}): Resolver<A, O>;
+
+/**
+ * Thrown by a resolver to put a specific error on the client's response.
+ *
+ * Anything else a handler throws is reported as an internal failure with its
+ * message withheld — a driver error can carry a connection string, and the
+ * caller is the public internet — so this is how a resolver says more than
+ * that. envio-serve carries the extensions through unchanged.
+ *
+ * ```ts
+ * throw new ResolverError("Service is syncing", {
+ *   code: "SERVICE_UNAVAILABLE",
+ *   httpStatus: 503,
+ * });
+ * ```
+ */
+export declare class ResolverError extends Error {
+  constructor(
+    message: string,
+    options?: {
+      /** Becomes `extensions.code`. Defaults to `"INTERNAL_SERVER_ERROR"`. */
+      readonly code?: string;
+      /** Becomes `extensions.http.status`. */
+      readonly httpStatus?: number;
+      /** Merged into `extensions` alongside `code`. */
+      readonly extensions?: Record<string, unknown>;
+    }
+  );
+  readonly code: string;
+  readonly httpStatus?: number;
+  readonly extensions?: Record<string, unknown>;
+}
+
+/** Names a schema so it can appear in the GraphQL schema as an object type. */
+export function defineType<F extends Record<string, unknown>>(
+  name: string,
+  fields: F
+): Sury.Schema<UnknownToOutput<F>>;
+
+/**
+ * Names a schema that appears in an argument.
+ *
+ * GraphQL keeps input and output types in a separate namespace from object
+ * types, so a `where` argument is declared with this rather than with
+ * {@link defineType}.
+ */
+export function defineInput<F extends Record<string, unknown>>(
+  name: string,
+  fields: F
+): Sury.Schema<UnknownToOutput<F>>;
+
+/** Every resolver declared so far, in declaration order. */
+export function getRegisteredResolvers(): readonly Resolver<unknown, unknown>[];
+
+/** The manifest and SDL for everything declared so far. */
+export function buildRegisteredManifest(): { manifest: unknown; sdl: string };
+
+/** Names a schema representing a GraphQL enum. */
+export function defineEnum<const V extends readonly string[]>(
+  name: string,
+  values: V
+): Sury.Schema<V[number]>;
+
+/** Names a schema representing a custom GraphQL scalar, such as `BigInt`. */
+export function defineScalar<T>(
+  name: string,
+  schema: Sury.Schema<T>
+): Sury.Schema<T>;
+
 // ============== Runtime values ==============
 
 /** The indexer instance. Register handlers with `indexer.onEvent`,

package/index.js

@@ -9,6 +9,16 @@ import { schema as bigDecimalSchema } from "./src/bindings/BigDecimal.res.mjs";
 
 export * from "./src/Envio.res.mjs";
 export { indexer, createTestIndexer } from "./src/Api.res.mjs";
+export {
+  createResolver,
+  defineType,
+  defineInput,
+  defineEnum,
+  defineScalar,
+  getRegisteredResolvers,
+  buildRegisteredManifest,
+  ResolverError,
+} from "./src/resolvers/index.js";
 export { default as BigDecimal } from "bignumber.js";
 
 // Important! Should match the index.d.ts file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envio",
-  "version": "3.14.0-subgraph",
+  "version": "3.14.1-resolvers.2",
   "type": "module",
   "description": "A latency and sync speed optimized, developer friendly blockchain data indexer.",
   "bin": "./bin.mjs",
@@ -54,10 +54,10 @@
     "postgres": "3.4.8"
   },
   "optionalDependencies": {
-    "envio-linux-x64": "3.14.0-subgraph",
-    "envio-linux-x64-musl": "3.14.0-subgraph",
-    "envio-linux-arm64": "3.14.0-subgraph",
-    "envio-darwin-x64": "3.14.0-subgraph",
-    "envio-darwin-arm64": "3.14.0-subgraph"
+    "envio-linux-x64": "3.14.1-resolvers.2",
+    "envio-linux-x64-musl": "3.14.1-resolvers.2",
+    "envio-linux-arm64": "3.14.1-resolvers.2",
+    "envio-darwin-x64": "3.14.1-resolvers.2",
+    "envio-darwin-arm64": "3.14.1-resolvers.2"
   }
 }

package/src/Bin.res

@@ -18,11 +18,13 @@ type startCmd = {
 }
 type migrateCmd = {reset: bool, config: JSON.t}
 type dropSchemaCmd = {config: JSON.t}
+type resolversCmd = {mode: string, cwd: string, env: dict<JSON.t>, config: JSON.t}
 
 type command =
   | Start(startCmd)
   | Migrate(migrateCmd)
   | DropSchema(dropSchemaCmd)
+  | Resolvers(resolversCmd)
 
 let decodeCommand = (json: JSON.t): command => {
   let obj = switch json->JSON.Decode.object {
@@ -37,6 +39,7 @@ let decodeCommand = (json: JSON.t): command => {
   | "start" => Start(json->(Utils.magic: JSON.t => startCmd))
   | "migrate" => Migrate(json->(Utils.magic: JSON.t => migrateCmd))
   | "drop-schema" => DropSchema(json->(Utils.magic: JSON.t => dropSchemaCmd))
+  | "resolvers" => Resolvers(json->(Utils.magic: JSON.t => resolversCmd))
   | other => JsError.throwWithMessage(`Unknown command kind: ${other}`)
   }
 }
@@ -67,6 +70,12 @@ let run = async args => {
           Config.prime(config)
           processChdir(cwd)
           applyEnv(env)
+          // `envio dev` only — see ResolverProcess.startForDev. Deployed, the
+          // resolvers are their own service and are never started from here.
+          let loaded = Config.load()
+          if loaded.isDev {
+            let _ = await ResolverProcess.startForDev(~config=loaded, ~projectRoot=cwd)
+          }
           await Main.start(~reset)
         | Migrate({reset, config}) =>
           Config.prime(config)
@@ -74,6 +83,45 @@ let run = async args => {
         | DropSchema({config}) =>
           Config.prime(config)
           await Main.dropSchema()
+        | Resolvers({mode, cwd, env, config}) =>
+          Config.prime(config)
+          processChdir(cwd)
+          applyEnv(env)
+          switch mode {
+          | "manifest" =>
+            await ResolverProcess.writeManifest(~config=Config.load(), ~projectRoot=cwd)
+          | "metadata" =>
+            let handlerUrl = switch Env.Resolvers.publicUrl() {
+            | Some(url) => url
+            | None =>
+              JsError.throwWithMessage(
+                "ENVIO_RESOLVERS_PUBLIC_URL is not set. It is the URL Hasura posts to and is baked into every action, so the metadata cannot be printed without it.",
+              )
+            }
+            let metadata = await ResolverProcess.metadataJson(
+              ~config=Config.load(),
+              ~projectRoot=cwd,
+              ~handlerUrl,
+            )
+            // stdout, so it pipes into `hasura metadata apply` or `jq` rather
+            // than being buried in the log stream.
+            Console.log(JSON.stringify(metadata, ~space=2))
+          | "migrate" =>
+            let {applied, reasons} = await ResolverProcess.migrate(
+              ~config=Config.load(),
+              ~projectRoot=cwd,
+            )
+            Logging.info(
+              applied
+                ? `Updated Hasura to match these resolvers: ${reasons->Array.join("; ")}`
+                : "Hasura already matches these resolvers; nothing to update",
+            )
+          // Serving keeps the event loop alive on its own, so returning here
+          // leaves the process running rather than exiting.
+          | _ =>
+            let running = await ResolverProcess.serve(~config=Config.load(), ~projectRoot=cwd)
+            running->ResolverProcess.handleSignals
+          }
         }
       }
     }

package/src/Bin.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Env from "./Env.res.mjs";
 import * as Core from "./Core.res.mjs";
 import * as Main from "./Main.res.mjs";
 import * as Utils from "./Utils.res.mjs";
@@ -12,6 +13,7 @@ import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.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 ResolverProcess from "./resolvers/ResolverProcess.res.mjs";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 
 let setEnvVar = ((k, v) => { process.env[k] = v; });
@@ -37,6 +39,11 @@ function decodeCommand(json) {
         TAG: "Migrate",
         _0: json
       };
+    case "resolvers" :
+      return {
+        TAG: "Resolvers",
+        _0: json
+      };
     case "start" :
       return {
         TAG: "Start",
@@ -70,9 +77,14 @@ async function run(args) {
     switch (match.TAG) {
       case "Start" :
         let match$1 = match._0;
+        let cwd = match$1.cwd;
         Config.prime(match$1.config);
-        process.chdir(match$1.cwd);
+        process.chdir(cwd);
         applyEnv(match$1.env);
+        let loaded = Config.load();
+        if (loaded.isDev) {
+          await ResolverProcess.startForDev(loaded, cwd);
+        }
         return await Main.start(undefined, match$1.reset, undefined, undefined, undefined);
       case "Migrate" :
         let match$2 = match._0;
@@ -81,6 +93,27 @@ async function run(args) {
       case "DropSchema" :
         Config.prime(match._0.config);
         return await Main.dropSchema();
+      case "Resolvers" :
+        let match$3 = match._0;
+        let cwd$1 = match$3.cwd;
+        Config.prime(match$3.config);
+        process.chdir(cwd$1);
+        applyEnv(match$3.env);
+        switch (match$3.mode) {
+          case "manifest" :
+            return await ResolverProcess.writeManifest(Config.load(), cwd$1);
+          case "metadata" :
+            let url = Env.Resolvers.publicUrl();
+            let handlerUrl = url !== undefined ? url : Stdlib_JsError.throwWithMessage("ENVIO_RESOLVERS_PUBLIC_URL is not set. It is the URL Hasura posts to and is baked into every action, so the metadata cannot be printed without it.");
+            let metadata = await ResolverProcess.metadataJson(Config.load(), cwd$1, handlerUrl);
+            console.log(JSON.stringify(metadata, undefined, 2));
+            return;
+          case "migrate" :
+            let match$4 = await ResolverProcess.migrate(Config.load(), cwd$1);
+            return Logging.info(match$4.applied ? `Updated Hasura to match these resolvers: ` + match$4.reasons.join("; ") : "Hasura already matches these resolvers; nothing to update");
+          default:
+            return ResolverProcess.handleSignals(await ResolverProcess.serve(Config.load(), cwd$1, undefined, undefined, undefined, undefined));
+        }
     }
   } catch (raw_exn) {
     let exn = Primitive_exceptions.internalToException(raw_exn);

package/src/Config.res

@@ -106,6 +106,9 @@ type t = {
   name: string,
   description: option<string>,
   handlers: string,
+  // Relative path to the module declaring custom GraphQL resolvers, when the
+  // project ships them. None means entity fields only.
+  resolvers: option<string>,
   contractHandlers: array<contractHandler>,
   shouldRollbackOnReorg: bool,
   shouldSaveFullHistory: bool,
@@ -151,9 +154,6 @@ type t = {
   // reach, so its checkpoints have to be comparable across chains.
   checkpointSequence: CheckpointSequence.t,
   envioInfo: JSON.t,
-  // Set only in subgraph mode: the translated manifest, which is what makes
-  // the subgraph runtime take over handler registration.
-  subgraph: option<JSON.t>,
 }
 
 type rpcSourceFor = | @as("sync") Sync | @as("fallback") Fallback | @as("realtime") Realtime
@@ -600,6 +600,7 @@ let publicConfigSchema = S.schema(s =>
     "name": s.matches(S.string),
     "description": s.matches(S.option(S.string)),
     "handlers": s.matches(S.option(S.string)),
+    "resolvers": 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)),
@@ -615,7 +616,6 @@ let publicConfigSchema = S.schema(s =>
     "svm": s.matches(S.option(publicConfigEcosystemSchema)),
     "enums": s.matches(S.option(S.dict(S.array(S.string)))),
     "entities": s.matches(S.option(S.array(entityJsonSchema))),
-    "subgraph": s.matches(S.option(S.json(~validate=false))),
   }
 )
 
@@ -688,8 +688,12 @@ let withProjectFlags = (command, ~config: t) =>
 
 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
+// Where the custom GraphQL resolvers live. Nothing about what is indexed or
+// how it is stored, so adopting resolvers must not read as a config change.
+let servingFields = ["resolvers"]
+
+// What `envio_info` records: the public config without the command's fields,
+// the serving 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.
@@ -698,10 +702,7 @@ let toEnvioInfo = (publicConfigJson: JSON.t): JSON.t => {
   switch envioInfo {
   | Object(obj) => {
       commandFields->Array.forEach(field => obj->Utils.Dict.deleteInPlace(field))
-      // The subgraph blob is how the runtime finds mappings. None of it
-      // describes stored data — that's already in `evm` / `entities` — so a
-      // specVersion bump or a mapping-path edit must not force a reset.
-      obj->Utils.Dict.deleteInPlace("subgraph")
+      servingFields->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")
@@ -1167,6 +1168,7 @@ let fromPublic = (publicConfigJson: JSON.t) => {
     name: publicConfig["name"],
     description: publicConfig["description"],
     handlers: publicConfig["handlers"]->Option.getOr("src/handlers"),
+    resolvers: publicConfig["resolvers"],
     contractHandlers,
     shouldRollbackOnReorg: publicConfig["rollbackOnReorg"]->Option.getOr(true),
     shouldSaveFullHistory: publicConfig["saveFullHistory"]->Option.getOr(false),
@@ -1191,7 +1193,6 @@ let fromPublic = (publicConfigJson: JSON.t) => {
     allEnums,
     checkpointSequence: CheckpointSequence.fromEntities(userEntities),
     envioInfo: publicConfigJson->toEnvioInfo,
-    subgraph: publicConfig["subgraph"],
   }
 
   switch publicConfig["isolatedChains"] {

package/src/Config.res.mjs

@@ -436,6 +436,7 @@ let publicConfigSchema = S$RescriptSchema.schema(s => ({
   name: s.m(S$RescriptSchema.string),
   description: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
   handlers: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
+  resolvers: 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)),
@@ -450,8 +451,7 @@ let publicConfigSchema = S$RescriptSchema.schema(s => ({
   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))),
-  subgraph: s.m(S$RescriptSchema.option(S$RescriptSchema.json(false)))
+  entities: s.m(S$RescriptSchema.option(S$RescriptSchema.array(entityJsonSchema)))
 }));
 
 function contractMappingOf(chainConfigs) {
@@ -517,11 +517,13 @@ let ecosystemFields = [
   "svm"
 ];
 
+let servingFields = ["resolvers"];
+
 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));
-    Utils.Dict.deleteInPlace(envioInfo, "subgraph");
+    servingFields.forEach(field => Utils.Dict.deleteInPlace(envioInfo, field));
     ecosystemFields.forEach(ecosystem => {
       let match = envioInfo[ecosystem];
       if (typeof match === "object" && match !== null && !Array.isArray(match)) {
@@ -830,6 +832,7 @@ function fromPublic(publicConfigJson) {
   let config_name = publicConfig.name;
   let config_description = publicConfig.description;
   let config_handlers = Stdlib_Option.getOr(publicConfig.handlers, "src/handlers");
+  let config_resolvers = publicConfig.resolvers;
   let config_shouldRollbackOnReorg = Stdlib_Option.getOr(publicConfig.rollbackOnReorg, true);
   let config_shouldSaveFullHistory = Stdlib_Option.getOr(publicConfig.saveFullHistory, false);
   let config_chainIdMode = Stdlib_Option.getOr(publicConfig.chainIdMode, "int32");
@@ -841,11 +844,11 @@ function fromPublic(publicConfigJson) {
   let config_projectFlags = Stdlib_Option.getOr(publicConfig.projectFlags, "");
   let config_checkpointSequence = CheckpointSequence.fromEntities(userEntities);
   let config_envioInfo = toEnvioInfo(publicConfigJson);
-  let config_subgraph = publicConfig.subgraph;
   let config = {
     name: config_name,
     description: config_description,
     handlers: config_handlers,
+    resolvers: config_resolvers,
     contractHandlers: contractHandlers,
     shouldRollbackOnReorg: config_shouldRollbackOnReorg,
     shouldSaveFullHistory: config_shouldSaveFullHistory,
@@ -869,8 +872,7 @@ function fromPublic(publicConfigJson) {
     userEntities: userEntities,
     allEnums: allEnums,
     checkpointSequence: config_checkpointSequence,
-    envioInfo: config_envioInfo,
-    subgraph: config_subgraph
+    envioInfo: config_envioInfo
   };
   let chainIds = publicConfig.isolatedChains;
   if (chainIds !== undefined) {
@@ -1188,6 +1190,7 @@ export {
   commandFields,
   withProjectFlags,
   ecosystemFields,
+  servingFields,
   toEnvioInfo,
   fromPublic,
   normalizeUserAddress,