envio 3.9.0 → 3.10.0-subgraph

package/src/Config.res.mjs

@@ -17,6 +17,7 @@ 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";
@@ -73,12 +74,6 @@ let publicConfigChainSchema = S$RescriptSchema.schema(s => ({
 
 let svmEventDescriptorSchema = S$RescriptSchema.schema(s => ({
   discriminator: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
-  discriminatorByteLen: s.m(S$RescriptSchema.int),
-  accountFilters: s.m(S$RescriptSchema.option(S$RescriptSchema.array(S$RescriptSchema.array(S$RescriptSchema.schema(s => ({
-    position: s.m(S$RescriptSchema.int),
-    values: s.m(S$RescriptSchema.array(S$RescriptSchema.string))
-  })))))),
-  isInner: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   accounts: s.m(S$RescriptSchema.option(S$RescriptSchema.array(S$RescriptSchema.string))),
   args: s.m(S$RescriptSchema.option(S$RescriptSchema.json(false)))
 }));
@@ -226,6 +221,12 @@ function getFieldTypeAndSchema(prop, enumConfigsByName) {
         S$RescriptSchema.bool
       ];
       break;
+    case "bytes" :
+      match = [
+        "Bytea",
+        Utils.Schema.bytes
+      ];
+      break;
     case "date" :
       match = [
         "Date",
@@ -277,10 +278,20 @@ function getFieldTypeAndSchema(prop, enumConfigsByName) {
       match = Stdlib_JsError.throwWithMessage("Unknown field type in entity config: " + typ);
   }
   let baseSchema = match[1];
-  let fieldSchema = isArray ? S$RescriptSchema.array(baseSchema) : baseSchema;
-  let fieldSchema$1 = isNullable ? S$RescriptSchema.$$null(fieldSchema) : fieldSchema;
+  let fieldType = match[0];
+  let fieldSchema;
+  let exit = 0;
+  if (typeof fieldType !== "object" && fieldType === "Bytea" && isArray) {
+    fieldSchema = Utils.Schema.bytesArray;
+  } else {
+    exit = 1;
+  }
+  if (exit === 1) {
+    fieldSchema = isArray ? S$RescriptSchema.array(baseSchema) : baseSchema;
+  }
+  let fieldSchema$1 = isNullable ? Utils.Schema.nullTolerant(fieldSchema) : fieldSchema;
   return [
-    match[0],
+    fieldType,
     fieldSchema$1,
     isNullable,
     isArray,
@@ -390,7 +401,8 @@ 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)))
+  entities: s.m(S$RescriptSchema.option(S$RescriptSchema.array(entityJsonSchema))),
+  subgraph: s.m(S$RescriptSchema.option(S$RescriptSchema.json(false)))
 }));
 
 function contractMappingOf(chainConfigs) {
@@ -527,11 +539,7 @@ function fromPublic(publicConfigJson) {
               ) : addresses[0];
             let s = eventItem.svm;
             let svm = s !== undefined ? Primitive_option.valFromOption(s) : Stdlib_JsError.throwWithMessage(`SVM instruction ` + contractName + `.` + eventName + ` is missing the "svm" descriptor in internal config`);
-            let accountFilters = Stdlib_Option.getOr(svm.accountFilters, []).map(group => group.map(af => ({
-              position: af.position,
-              values: af.values
-            })));
-            return EventConfigBuilder.buildSvmInstructionEventConfig(contractName, eventName, programId, svm.discriminator, svm.discriminatorByteLen, accountFilters, svm.isInner, Stdlib_Option.getOr(svm.accounts, []), Stdlib_Option.getOr(svm.args, null), svmDefinedTypes);
+            return EventConfigBuilder.buildSvmInstructionEventConfig(contractName, eventName, programId, svm.discriminator, Stdlib_Option.getOr(svm.accounts, []), Stdlib_Option.getOr(svm.args, null), svmDefinedTypes);
         }
       });
     } else {
@@ -722,10 +730,19 @@ function fromPublic(publicConfigJson) {
     isDev: Stdlib_Option.getOr(publicConfig.isDev, false),
     userEntitiesByName: userEntitiesByName,
     userEntities: userEntities,
-    allEnums: allEnums
+    allEnums: allEnums,
+    subgraph: publicConfig.subgraph
   };
 }
 
+function isIsolatedMultichain(config) {
+  if (ChainMap.keys(config.chainMap).length > 1) {
+    return config.userEntities.every(entityConfig => !entityConfig.crossChain);
+  } else {
+    return false;
+  }
+}
+
 function normalizeUserAddress(config, address) {
   let match = config.ecosystem.name;
   switch (match) {
@@ -789,11 +806,15 @@ function getEventConfig(config, contractName, eventName, chainId) {
   });
 }
 
-function shouldSaveHistory(config, isInReorgThreshold) {
+function shouldSaveHistory(config, isInReorgThreshold, chainId) {
   if (config.shouldSaveFullHistory) {
     return true;
-  } else if (config.shouldRollbackOnReorg) {
-    return isInReorgThreshold;
+  } else if (config.shouldRollbackOnReorg && isInReorgThreshold) {
+    if (chainId !== undefined && isIsolatedMultichain(config)) {
+      return ChainMap.get(config.chainMap, Primitive_option.valFromOption(chainId)).maxReorgDepth > 0;
+    } else {
+      return true;
+    }
   } else {
     return false;
   }
@@ -867,6 +888,7 @@ function stripSensitiveData(json) {
     stripChains(cloned["evm"]);
     stripChains(cloned["fuel"]);
     stripChains(cloned["svm"]);
+    Utils.Dict.deleteInPlace(cloned, "subgraph");
   }
   return cloned;
 }
@@ -1031,6 +1053,19 @@ function throwIfIncompatible(changedPaths, resetCommand, runCommand, hasClickhou
   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);
+}
+
 function load() {
   let c = cached.contents;
   if (c !== undefined) {
@@ -1075,6 +1110,7 @@ export {
   publicConfigSchema,
   contractMappingOf,
   fromPublic,
+  isIsolatedMultichain,
   normalizeUserAddress,
   normalizeSimulateAddress,
   getEventConfig,
@@ -1087,6 +1123,7 @@ export {
   canonicalJson,
   diffPaths,
   throwIfIncompatible,
+  throwIfResumeIncompatible,
   load,
   getPgUserEntities,
 }

package/src/Core.res

@@ -10,6 +10,7 @@ type svmHyperSyncClientCtor
 type fuelHyperSyncClientCtor
 type transactionStoreCtor
 type blockStoreCtor
+type clickHouseSinkCtor
 type addressStoreCtor
 // Test-only: a local HyperSync server, bound by MockHyperSyncServer in envio-tests.
 type mockHyperSyncServerCtor
@@ -26,9 +27,18 @@ 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,
+  isSvmPubkey: (~value: string) => bool,
   fromUserApi: (string, fromUserApiOptions) => fromUserApiResult,
   runCli: (~args: array<string>, ~envioPackageDir: Null.t<string>) => promise<Null.t<string>>,
   @as("EvmHyperSyncClient")
@@ -45,6 +55,8 @@ type addon = {
   blockStore: blockStoreCtor,
   @as("AddressStore")
   addressStore: addressStoreCtor,
+  @as("ClickHouseSink")
+  clickHouseSink: clickHouseSinkCtor,
   @as("MockHyperSyncServer")
   mockHyperSyncServer: mockHyperSyncServerCtor,
   encodeAddresses: (~ecosystem: string, ~addresses: array<Address.t>) => array<NodeJs.Buffer.t>,
@@ -257,6 +269,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

@@ -195,6 +195,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);
@@ -212,6 +222,7 @@ export {
   getAddon,
   getConfigJson,
   fromUserApi,
+  fromSubgraph,
   runCli,
 }
 /* envioPackageDir Not a pure module */

package/src/CrossChainState.res

@@ -72,31 +72,23 @@ let totalReadyCount = (crossChainState: t) => {
 let nextItemIsNone = (crossChainState: t): bool =>
   !(crossChainState.chainStates->Dict.valuesToArray->Array.some(ChainState.hasReadyItem))
 
-let getSafeCheckpointId = (crossChainState: t) => {
-  let result: ref<option<bigint>> = ref(None)
-
-  for i in 0 to crossChainState.chainIds->Array.length - 1 {
-    let cs = crossChainState->getChainState(crossChainState.chainIds->Array.getUnsafe(i))
-    switch cs->ChainState.safeCheckpointTracking {
-    | None => () // Skip chains with maxReorgDepth = 0
-    | Some(safeCheckpointTracking) =>
-      let safeCheckpointId =
-        safeCheckpointTracking->SafeCheckpointTracking.getSafeCheckpointId(
+// Each chain's safe checkpoint: the last one a reorg on that chain can no longer
+// reach, or None while it has nothing safe yet. A chain that can't be rolled
+// back (maxReorgDepth = 0) tracks none, and everything it has committed is safe.
+let getSafeCheckpointIdByChain = (crossChainState: t, ~committedCheckpointId) =>
+  crossChainState.chainIds->Array.map(chainId => {
+    let cs = crossChainState->getChainState(chainId)
+    (
+      chainId,
+      switch cs->ChainState.safeCheckpointTracking {
+      | None => Some(committedCheckpointId)
+      | Some(tracking) =>
+        tracking->SafeCheckpointTracking.getSafeCheckpointId(
           ~sourceBlockNumber=cs->ChainState.knownHeight,
         )
-      switch result.contents {
-      | None => result := Some(safeCheckpointId)
-      | Some(current) if safeCheckpointId < current => result := Some(safeCheckpointId)
-      | _ => ()
-      }
-    }
-  }
-
-  switch result.contents {
-  | Some(id) if id > 0n => Some(id)
-  | _ => None // No safe checkpoint found
-  }
-}
+      },
+    )
+  })
 
 // --- Cross-chain transitions. ---
 

package/src/CrossChainState.res.mjs

@@ -65,23 +65,15 @@ function nextItemIsNone(crossChainState) {
   return !Object.values(crossChainState.chainStates).some(ChainState.hasReadyItem);
 }
 
-function getSafeCheckpointId(crossChainState) {
-  let result;
-  for (let i = 0, i_finish = crossChainState.chainIds.length; i < i_finish; ++i) {
-    let cs = crossChainState.chainStates[crossChainState.chainIds[i]];
-    let safeCheckpointTracking = ChainState.safeCheckpointTracking(cs);
-    if (safeCheckpointTracking !== undefined) {
-      let safeCheckpointId = SafeCheckpointTracking.getSafeCheckpointId(safeCheckpointTracking, ChainState.knownHeight(cs));
-      let current = result;
-      if (!(current !== undefined && safeCheckpointId >= current)) {
-        result = safeCheckpointId;
-      }
-    }
-  }
-  let id = result;
-  if (id !== undefined && id > 0n) {
-    return id;
-  }
+function getSafeCheckpointIdByChain(crossChainState, committedCheckpointId) {
+  return crossChainState.chainIds.map(chainId => {
+    let cs = crossChainState.chainStates[chainId];
+    let tracking = ChainState.safeCheckpointTracking(cs);
+    return [
+      chainId,
+      tracking !== undefined ? SafeCheckpointTracking.getSafeCheckpointId(tracking, ChainState.knownHeight(cs)) : committedCheckpointId
+    ];
+  });
 }
 
 function createBatch(crossChainState, processedCheckpointId, batchSizeTarget, isRollback) {
@@ -261,7 +253,7 @@ export {
   isInReorgThreshold,
   targetBufferSize,
   nextItemIsNone,
-  getSafeCheckpointId,
+  getSafeCheckpointIdByChain,
   createBatch,
   enterReorgThreshold,
   applyBatchProgress,

package/src/CrossChainState.resi

@@ -21,7 +21,10 @@ let targetBufferSize: t => int
 
 // Derived (pure).
 let nextItemIsNone: t => bool
-let getSafeCheckpointId: t => option<Internal.checkpointId>
+let getSafeCheckpointIdByChain: (
+  t,
+  ~committedCheckpointId: Internal.checkpointId,
+) => array<(ChainId.t, option<Internal.checkpointId>)>
 
 // Cross-chain transitions.
 let createBatch: (

package/src/Ecosystem.res

@@ -10,6 +10,11 @@ type t = {
       for SVM. Centralised here so adding a new ecosystem only requires a
       new ecosystem record, not another switch in `Main.res`. */
   onBlockMethodName: string,
+  /** What the ecosystem calls a contract and one of its events, for
+      registration errors that are shared across ecosystems — "contract" /
+      "event" on EVM and Fuel, "program" / "instruction" on SVM. */
+  contractNoun: string,
+  eventNoun: string,
   /** Schema that unwraps the ecosystem-specific outer wrapper around the
       user's `where`-returned filter (`block.number` on EVM, `block.height`
       on Fuel, `slot` on SVM) and surfaces the raw inner `{_gte?, _lte?,
@@ -23,8 +28,8 @@ type t = {
       `option<unknown>`. Separate from `onBlockFilterSchema` because event
       block filters support only `_gte` (→ per-event `startBlock`) — `_lte`
       and `_every` are rejected by the inner `eventBlockRangeSchema` in
-      `LogSelection.res`. SVM does not support event handlers, so its
-      schema always surfaces `None`. */
+      `LogSelection.res`. SVM parses its own `where` (including the
+      `block.slot` chunk), so its schema always surfaces `None`. */
   onEventBlockFilterSchema: S.t<option<unknown>>,
   /** Base logger injected at construction. Used to build per-item child
       loggers (see `getItemLogger`). */

package/src/Envio.res

@@ -83,10 +83,12 @@ type svmInstruction = {
   instructionName: string,
   discriminator: string,
   programId?: SvmTypes.Pubkey.t,
-  data?: string,
+  data?: Uint8Array.t,
   path?: array<int>,
   isInner?: bool,
-  args?: JSON.t,
+  // Decoded Borsh args; wide integers (u64/u128/i64/i128) are bigint, so the
+  // tree is not valid JSON.
+  args?: unknown,
   accounts?: dict<svmInstructionAccount>,
   accountArguments?: array<SvmTypes.Pubkey.t>,
   transaction?: svmTransaction,
@@ -283,9 +285,9 @@ type svmSimulateItem = {
   slot?: int,
   path?: array<int>,
   programId?: string,
-  data?: string,
+  data?: Uint8Array.t,
   isInner?: bool,
-  args?: JSON.t,
+  args?: unknown,
   accounts?: dict<{address: string}>,
   accountArguments?: array<string>,
   logs?: array<{kind?: string, message?: string}>,

package/src/EventConfigBuilder.res

@@ -317,9 +317,6 @@ let svmSelectionKinds = ["instruction", "transaction", "accountActivity", "block
 // typo, and an unrecognised key would read as an empty selection — silently
 // dropping every field `config.yaml` selected. Rejected here so the option is
 // held to the same shape whether or not the project type-checks it.
-let quotedJoin = (names: array<string>) =>
-  names->Array.map(name => `"${name}"`)->Array.joinUnsafe(", ")
-
 let validateFieldsShapeOrThrow = (
   fields: unknown,
   ~registration: string,
@@ -337,7 +334,7 @@ let validateFieldsShapeOrThrow = (
   ->Array.forEach(key =>
     if !(validKeys->Array.includes(key)) {
       JsError.throwWithMessage(
-        `Invalid "${key}" key in the fields option of ${registration}. Valid keys: ${quotedJoin(
+        `Invalid "${key}" key in the fields option of ${registration}. Valid keys: ${Utils.Array.quotedJoin(
             validKeys,
           )}.`,
       )
@@ -373,7 +370,7 @@ let parseFieldsOrThrow = (
   fields->Array.forEach(name => {
     if !(valid->Utils.Set.has(name)) {
       JsError.throwWithMessage(
-        `Invalid "${name}" field in the fields.${kind} option of ${registration}. Valid ${kind} fields: ${quotedJoin(
+        `Invalid "${name}" field in the fields.${kind} option of ${registration}. Valid ${kind} fields: ${Utils.Array.quotedJoin(
           valid->Utils.Set.toArray,
         )}.`,
       )
@@ -577,7 +574,7 @@ let resolveSvmInlineFieldSelection = (
   ~contractName: string,
   ~eventName: string,
 ): Internal.fieldSelection => {
-  let registration = `the "${eventName}" event registration on contract "${contractName}"`
+  let registration = `the "${eventName}" instruction on program "${contractName}"`
   validateFieldsShapeOrThrow(
     fields,
     ~registration,
@@ -638,9 +635,6 @@ let buildSvmInstructionEventConfig = (
   ~instructionName: string,
   ~programId: SvmTypes.Pubkey.t,
   ~discriminator: option<string>,
-  ~discriminatorByteLen: int,
-  ~accountFilters: array<Internal.svmAccountFilterGroup>,
-  ~isInner: option<bool>,
   ~accounts: array<string>=[],
   ~args: JSON.t=JSON.Null,
   ~definedTypes: JSON.t=JSON.Null,
@@ -667,38 +661,187 @@ let buildSvmInstructionEventConfig = (
     simulateParamsSchema: paramsSchema,
     programId,
     discriminator,
-    discriminatorByteLen,
     fieldSelection,
-    accountFilters,
-    isInner,
     accounts,
     args,
     definedTypes,
   }
 }
 
-// Enrich an SVM definition into a registration. SVM has no `where`; only the
-// handler binding + wildcard-derived address gate are registration state.
+// ============== SVM `where` ==============
+
+type parsedSvmWhere = {
+  // Disjunctive normal form: outer array is OR of AND-groups. Empty means the
+  // registration accepts any accounts.
+  accountFilters: array<Internal.svmAccountFilterGroup>,
+  isInner: option<bool>,
+  startBlock: option<int>,
+}
+
+let validSvmWhereKeys = ["accounts", "isInner", "block"]
+
+// `{slot: {_gte?}}`. Both levels are strict: the inner `eventBlockRangeSchema`
+// rejects the `_lte` / `_every` that only `onSlot` supports, the outer rejects
+// a wrapper key other than `slot`.
+type svmBlockFilter = {slot?: LogSelection.eventBlockRange}
+let svmBlockFilterSchema: S.t<svmBlockFilter> = S.object(s => {
+  slot: ?s.field("slot", S.option(LogSelection.eventBlockRangeSchema)),
+})->S.strict
+
+// The source query narrows accounts through `a0..a9`, so only an instruction's
+// leading account slots can be filtered.
+let filterableAccountCount = 10
+
+// Resolve the `where` option of an `onInstruction` registration. Account names
+// are resolved against the instruction's declared accounts here, so the
+// registration carries positions and nothing downstream needs the names.
+let resolveSvmWhereOrThrow = (
+  where: JSON.t,
+  ~contractName: string,
+  ~eventName: string,
+  ~accountNames: array<string>,
+): parsedSvmWhere => {
+  let invalid = message =>
+    JsError.throwWithMessage(
+      `Invalid where configuration for the "${eventName}" instruction on program "${contractName}". ${message}`,
+    )
+
+  let obj = switch where {
+  | Object(obj) => obj
+  | _ => invalid("Expected an object.")
+  }
+  obj->Utils.Dict.forEachWithKey((_, key) =>
+    if !(validSvmWhereKeys->Array.includes(key)) {
+      invalid(`Unknown field "${key}". Valid fields: ${Utils.Array.quotedJoin(validSvmWhereKeys)}.`)
+    }
+  )
+
+  let isInner = switch obj->Dict.get("isInner") {
+  | None => None
+  | Some(Boolean(isInner)) => Some(isInner)
+  | Some(_) => invalid(`The "isInner" filter must be a boolean.`)
+  }
+
+  let parseGroup = (group: dict<JSON.t>): Internal.svmAccountFilterGroup =>
+    group
+    ->Dict.toArray
+    ->Array.map(((name, value)) => {
+      let position = switch accountNames->Array.indexOf(name) {
+      | -1 if accountNames->Utils.Array.isEmpty =>
+        invalid(
+          "The instruction has no named accounts to filter on. Add `accounts` and `args` to it in config.yaml, or attach an IDL.",
+        )
+      | -1 =>
+        invalid(
+          `The instruction has no account named "${name}" to filter on. Named accounts: ${Utils.Array.quotedJoin(
+              accountNames,
+            )}.`,
+        )
+      | position if position >= filterableAccountCount =>
+        invalid(
+          `Account "${name}" is at position ${position->Int.toString}, and only the first ${filterableAccountCount->Int.toString} accounts of an instruction can be filtered.`,
+        )
+      | position => position
+      }
+      let values = value->normalizeOrThrow
+      if values->Utils.Array.isEmpty {
+        invalid(`The "${name}" filter must list at least one pubkey.`)
+      }
+      {
+        Internal.position,
+        values: values->Array.map(value =>
+          switch value {
+          | JSON.String(pubkey) if Core.getAddon().isSvmPubkey(~value=pubkey) =>
+            pubkey->SvmTypes.Pubkey.fromStringUnsafe
+          | JSON.String(pubkey) =>
+            invalid(`The "${name}" filter value "${pubkey}" is not a base58 SVM pubkey.`)
+          | _ => invalid(`The "${name}" filter must list base58 pubkeys as strings.`)
+          }
+        ),
+      }
+    })
+
+  // An empty AND-group matches every instruction, so it makes the whole OR
+  // vacuous. Normalized away here so the source builds one unfiltered
+  // selection instead of a match-all selection beside the narrower ones.
+  let groups = switch obj->Dict.get("accounts") {
+  | None => []
+  | Some(Object(group)) => [parseGroup(group)]
+  | Some(Array(entries)) =>
+    entries->Array.map(entry =>
+      switch entry {
+      | Object(group) => parseGroup(group)
+      | _ => invalid(`Each entry in "accounts" must be an object.`)
+      }
+    )
+  | Some(_) => invalid(`Expected "accounts" to be an object or an array of objects.`)
+  }
+  let accountFilters = groups->Array.some(Utils.Array.isEmpty) ? [] : groups
+
+  let startBlock = switch obj->Dict.get("block") {
+  | None => None
+  | Some(block) =>
+    let filter = try block->S.parseOrThrow(svmBlockFilterSchema) catch {
+    | S.Raised(exn) =>
+      invalid(
+        `The "block" filter is invalid: ${exn
+          ->Utils.prettifyExn
+          ->(
+            Utils.magic: exn => string
+          )}. Only \`_gte\` is supported on instruction filters — use \`indexer.onSlot\` for \`_lte\` or \`_every\`.`,
+      )
+    }
+    switch filter.slot {
+    | Some({_gte}) => _gte
+    | None => None
+    }
+  }
+
+  {accountFilters, isInner, startBlock}
+}
+
+// Enrich an SVM definition into a registration: the handler binding plus the
+// `where`-derived account/isInner filters and startBlock override.
 let buildSvmOnEventRegistration = (
   ~eventConfig: Internal.svmInstructionEventConfig,
   ~isWildcard: bool,
   ~handler: option<Internal.handler>,
   ~contractRegister: option<Internal.contractRegister>,
+  ~where: option<JSON.t>,
   ~fieldSelection: option<Internal.fieldSelection>=?,
   ~startBlock: option<int>=?,
 ): Internal.svmOnEventRegistration => {
-  index: -1,
-  eventConfig: (eventConfig :> Internal.eventConfig),
-  handler,
-  contractRegister,
-  isWildcard,
-  filterByAddresses: false,
-  dependsOnAddresses: Internal.dependsOnAddresses(~isWildcard, ~filterByAddresses=false),
-  startBlock,
-  fieldSelection: switch fieldSelection {
-  | Some(fieldSelection) => fieldSelection
-  | None => eventConfig.fieldSelection
-  },
+  let resolvedWhere = switch where {
+  | None => {accountFilters: [], isInner: None, startBlock: None}
+  | Some(where) =>
+    where->resolveSvmWhereOrThrow(
+      ~contractName=eventConfig.contractName,
+      ~eventName=eventConfig.name,
+      ~accountNames=eventConfig.accounts,
+    )
+  }
+
+  {
+    index: -1,
+    eventConfig: (eventConfig :> Internal.eventConfig),
+    handler,
+    contractRegister,
+    isWildcard,
+    filterByAddresses: false,
+    dependsOnAddresses: Internal.dependsOnAddresses(~isWildcard, ~filterByAddresses=false),
+    // `where.block.slot._gte` overrides the program-level startBlock when
+    // present, mirroring EVM's `where.block.number._gte`.
+    startBlock: switch resolvedWhere.startBlock {
+    | Some(_) as sb => sb
+    | None => startBlock
+    },
+    fieldSelection: switch fieldSelection {
+    | Some(fieldSelection) => fieldSelection
+    | None => eventConfig.fieldSelection
+    },
+    accountFilters: resolvedWhere.accountFilters,
+    isInner: resolvedWhere.isInner,
+  }
 }
 
 // ============== Build Fuel event config ==============