envio 3.9.0 → 3.10.0

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
@@ -29,6 +30,7 @@ type fromUserApiResult = {
 type addon = {
   getConfigJson: (~configPath: Null.t<string>, ~directory: Null.t<string>) => string,
   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 +47,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>,

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 ==============

package/src/EventConfigBuilder.res.mjs

@@ -14,6 +14,7 @@ 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 S$RescriptSchema from "rescript-schema/src/S.res.mjs";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 
 let paramMetaSchema = S$RescriptSchema.recursive(self => S$RescriptSchema.object(s => ({
   name: s.f("name", S$RescriptSchema.string),
@@ -261,17 +262,13 @@ let svmSelectionKinds = [
   "log"
 ];
 
-function quotedJoin(names) {
-  return names.map(name => `"` + name + `"`).join(", ");
-}
-
 function validateFieldsShapeOrThrow(fields, registration, validKeys, shapeNoun) {
   if (typeof fields !== "object" || fields === null || Array.isArray(fields)) {
     Stdlib_JsError.throwWithMessage(`The fields option of ` + registration + ` must be an object of ` + shapeNoun + ` field names.`);
   }
   Object.keys(fields).forEach(key => {
     if (!validKeys.includes(key)) {
-      return Stdlib_JsError.throwWithMessage(`Invalid "` + key + `" key in the fields option of ` + registration + `. Valid keys: ` + quotedJoin(validKeys) + `.`);
+      return Stdlib_JsError.throwWithMessage(`Invalid "` + key + `" key in the fields option of ` + registration + `. Valid keys: ` + Utils.$$Array.quotedJoin(validKeys) + `.`);
     }
   });
 }
@@ -295,7 +292,7 @@ function parseFieldsOrThrow(fields, valid, kind, registration, rejectEmptyOpt) {
     ) : [];
   fields$1.forEach(name => {
     if (!valid.has(name)) {
-      Stdlib_JsError.throwWithMessage(`Invalid "` + name + `" field in the fields.` + kind + ` option of ` + registration + `. Valid ` + kind + ` fields: ` + quotedJoin(Array.from(valid)) + `.`);
+      Stdlib_JsError.throwWithMessage(`Invalid "` + name + `" field in the fields.` + kind + ` option of ` + registration + `. Valid ` + kind + ` fields: ` + Utils.$$Array.quotedJoin(Array.from(valid)) + `.`);
     }
     if (seen.has(name)) {
       Stdlib_JsError.throwWithMessage(`Duplicate "` + name + `" field in the fields.` + kind + ` option of ` + registration + `.`);
@@ -420,7 +417,7 @@ let validSvmLogFields = new Set([
 ]);
 
 function resolveSvmInlineFieldSelection(fields, contractName, eventName) {
-  let registration = `the "` + eventName + `" event registration on contract "` + contractName + `"`;
+  let registration = `the "` + eventName + `" instruction on program "` + contractName + `"`;
   validateFieldsShapeOrThrow(fields, registration, svmSelectionKinds, "instruction, transaction, accountActivity, block and log");
   let accountActivity = selectionList(fields, "accountActivity");
   let log = selectionList(fields, "log");
@@ -436,7 +433,7 @@ function resolveSvmInlineFieldSelection(fields, contractName, eventName) {
   return Internal.makeFieldSelection(blockFields, transactionFields, Primitive_option.some(instructionFields), Primitive_option.some(accountActivityFields), Primitive_option.some(logFields), Svm.eventBlockFieldMask, Svm.eventTransactionFieldMask);
 }
 
-function buildSvmInstructionEventConfig(contractName, instructionName, programId, discriminator, discriminatorByteLen, accountFilters, isInner, accountsOpt, argsOpt, definedTypesOpt) {
+function buildSvmInstructionEventConfig(contractName, instructionName, programId, discriminator, accountsOpt, argsOpt, definedTypesOpt) {
   let accounts = accountsOpt !== undefined ? accountsOpt : [];
   let args = argsOpt !== undefined ? argsOpt : null;
   let definedTypes = definedTypesOpt !== undefined ? definedTypesOpt : null;
@@ -451,16 +448,121 @@ function buildSvmInstructionEventConfig(contractName, instructionName, programId
     fieldSelection: fieldSelection,
     programId: programId,
     discriminator: discriminator,
-    discriminatorByteLen: discriminatorByteLen,
-    accountFilters: accountFilters,
-    isInner: isInner,
     accounts: accounts,
     args: args,
     definedTypes: definedTypes
   };
 }
 
-function buildSvmOnEventRegistration(eventConfig, isWildcard, handler, contractRegister, fieldSelection, startBlock) {
+let validSvmWhereKeys = [
+  "accounts",
+  "isInner",
+  "block"
+];
+
+let svmBlockFilterSchema = S$RescriptSchema.strict(S$RescriptSchema.object(s => ({
+  slot: s.f("slot", S$RescriptSchema.option(LogSelection.eventBlockRangeSchema))
+})));
+
+function resolveSvmWhereOrThrow(where, contractName, eventName, accountNames) {
+  let invalid = message => Stdlib_JsError.throwWithMessage(`Invalid where configuration for the "` + eventName + `" instruction on program "` + contractName + `". ` + message);
+  let obj;
+  obj = typeof where === "object" && where !== null && !Array.isArray(where) ? where : invalid("Expected an object.");
+  Utils.Dict.forEachWithKey(obj, (param, key) => {
+    if (!validSvmWhereKeys.includes(key)) {
+      return invalid(`Unknown field "` + key + `". Valid fields: ` + Utils.$$Array.quotedJoin(validSvmWhereKeys) + `.`);
+    }
+  });
+  let match = obj["isInner"];
+  let isInner = match !== undefined ? (
+      typeof match === "boolean" ? match : invalid(`The "isInner" filter must be a boolean.`)
+    ) : undefined;
+  let parseGroup = group => Object.entries(group).map(param => {
+    let name = param[0];
+    let position = accountNames.indexOf(name);
+    let position$1 = position !== -1 ? (
+        position >= 10 ? invalid(`Account "` + name + `" is at position ` + position.toString() + `, and only the first ` + (10).toString() + ` accounts of an instruction can be filtered.`) : position
+      ) : (
+        Utils.$$Array.isEmpty(accountNames) ? invalid("The instruction has no named accounts to filter on. Add `accounts` and `args` to it in config.yaml, or attach an IDL.") : invalid(`The instruction has no account named "` + name + `" to filter on. Named accounts: ` + Utils.$$Array.quotedJoin(accountNames) + `.`)
+      );
+    let values = normalizeOrThrow(param[1]);
+    if (Utils.$$Array.isEmpty(values)) {
+      invalid(`The "` + name + `" filter must list at least one pubkey.`);
+    }
+    return {
+      position: position$1,
+      values: values.map(value => {
+        if (typeof value === "string") {
+          if (Core.getAddon().isSvmPubkey(value)) {
+            return value;
+          } else {
+            return invalid(`The "` + name + `" filter value "` + value + `" is not a base58 SVM pubkey.`);
+          }
+        } else {
+          return invalid(`The "` + name + `" filter must list base58 pubkeys as strings.`);
+        }
+      })
+    };
+  });
+  let match$1 = obj["accounts"];
+  let groups;
+  if (match$1 !== undefined) {
+    if (Array.isArray(match$1)) {
+      groups = match$1.map(entry => {
+        if (typeof entry === "object" && entry !== null && !Array.isArray(entry)) {
+          return parseGroup(entry);
+        } else {
+          return invalid(`Each entry in "accounts" must be an object.`);
+        }
+      });
+    } else if (match$1 === null) {
+      groups = invalid(`Expected "accounts" to be an object or an array of objects.`);
+    } else {
+      switch (typeof match$1) {
+        case "object" :
+          groups = [parseGroup(match$1)];
+          break;
+        default:
+          groups = invalid(`Expected "accounts" to be an object or an array of objects.`);
+      }
+    }
+  } else {
+    groups = [];
+  }
+  let accountFilters = groups.some(Utils.$$Array.isEmpty) ? [] : groups;
+  let block = obj["block"];
+  let startBlock;
+  if (block !== undefined) {
+    let filter;
+    try {
+      filter = S$RescriptSchema.parseOrThrow(block, svmBlockFilterSchema);
+    } catch (raw_exn) {
+      let exn = Primitive_exceptions.internalToException(raw_exn);
+      if (exn.RE_EXN_ID === S$RescriptSchema.Raised) {
+        filter = invalid(`The "block" filter is invalid: ` + Utils.prettifyExn(exn._1) + `. Only \`_gte\` is supported on instruction filters — use \`indexer.onSlot\` for \`_lte\` or \`_every\`.`);
+      } else {
+        throw exn;
+      }
+    }
+    let match$2 = filter.slot;
+    startBlock = match$2 !== undefined ? match$2._gte : undefined;
+  } else {
+    startBlock = undefined;
+  }
+  return {
+    accountFilters: accountFilters,
+    isInner: isInner,
+    startBlock: startBlock
+  };
+}
+
+function buildSvmOnEventRegistration(eventConfig, isWildcard, handler, contractRegister, where, fieldSelection, startBlock) {
+  let resolvedWhere = where !== undefined ? resolveSvmWhereOrThrow(where, eventConfig.contractName, eventConfig.name, eventConfig.accounts) : ({
+      accountFilters: [],
+      isInner: undefined,
+      startBlock: undefined
+    });
+  let sb = resolvedWhere.startBlock;
   return {
     index: -1,
     eventConfig: eventConfig,
@@ -469,8 +571,10 @@ function buildSvmOnEventRegistration(eventConfig, isWildcard, handler, contractR
     isWildcard: isWildcard,
     filterByAddresses: false,
     dependsOnAddresses: Internal.dependsOnAddresses(isWildcard, false),
-    startBlock: startBlock,
-    fieldSelection: fieldSelection !== undefined ? fieldSelection : eventConfig.fieldSelection
+    startBlock: sb !== undefined ? sb : startBlock,
+    fieldSelection: fieldSelection !== undefined ? fieldSelection : eventConfig.fieldSelection,
+    accountFilters: resolvedWhere.accountFilters,
+    isInner: resolvedWhere.isInner
   };
 }
 
@@ -542,6 +646,8 @@ function buildFuelOnEventRegistration(eventConfig, isWildcard, handler, contract
   };
 }
 
+let filterableAccountCount = 10;
+
 export {
   paramMetaSchema,
   normalizeOrThrow,
@@ -561,7 +667,6 @@ export {
   rawEventBlockFields,
   evmSelectionKinds,
   svmSelectionKinds,
-  quotedJoin,
   validateFieldsShapeOrThrow,
   selectionList,
   validBlockFields,
@@ -578,6 +683,10 @@ export {
   validSvmLogFields,
   resolveSvmInlineFieldSelection,
   buildSvmInstructionEventConfig,
+  validSvmWhereKeys,
+  svmBlockFilterSchema,
+  filterableAccountCount,
+  resolveSvmWhereOrThrow,
   buildSvmOnEventRegistration,
   buildFuelEventConfig,
   buildFuelOnEventRegistration,