envio 3.6.1 → 3.7.0

package/src/HandlerRegister.res

@@ -82,6 +82,36 @@ let startRegistration = (~config: Config.t) => {
   }
 }
 
+// A registration a caller owns, rather than the single implicit one
+// `startRegistration` installs. Tests run several indexers in one process, each
+// with its own config, and handlers must register against the config they were
+// written for.
+type registration = activeRegistration
+
+let makeRegistration = (~config: Config.t): registration => {
+  config,
+  registrationsByChainId: Dict.make(),
+  finished: false,
+}
+
+// Makes `registration` the target of `indexer.onEvent` & co. for the duration
+// of `fn`, restoring whatever was active before — so one caller's handlers
+// never land in another's registration. Concurrent scopes would still clobber
+// each other: the pointer they swap is process-global.
+let useRegistration = async (registration: registration, fn) => {
+  let previous = EnvioGlobal.value.activeRegistration
+  EnvioGlobal.value.activeRegistration = Some(registration->(Utils.magic: registration => unknown))
+  let restore = () => EnvioGlobal.value.activeRegistration = previous
+  switch await fn() {
+  | result =>
+    restore()
+    result
+  | exception exn =>
+    restore()
+    throw(exn)
+  }
+}
+
 let getChainRegistrations = (r: activeRegistration, ~chainId: ChainId.t): chainRegistrations => {
   let key = chainId->ChainId.toString
   switch r.registrationsByChainId->Utils.Dict.dangerouslyGetNonOption(key) {
@@ -104,6 +134,7 @@ let buildOnEventRegistrationWith = (
   ~handler: option<Internal.handler>,
   ~contractRegister: option<Internal.contractRegister>,
   ~where: option<JSON.t>,
+  ~fieldSelection: option<Internal.fieldSelection>,
   ~startBlock=?,
 ): Internal.onEventRegistration => {
   switch config.ecosystem.name {
@@ -134,6 +165,7 @@ let buildOnEventRegistrationWith = (
       ~where,
       ~chainId,
       ~onEventBlockFilterSchema=config.ecosystem.onEventBlockFilterSchema,
+      ~fieldSelection?,
       ~startBlock?,
     ) :> Internal.onEventRegistration)
   }
@@ -163,6 +195,19 @@ let sameEventAndFilter = (
   | Fuel | Svm => true
   }
 
+// The merged registration keeps `base`'s handler and slot, picks up the
+// contractRegister from `other`, and carries the union of what both callbacks
+// read. Relies on `onEventRegistration` having an optional field so the spread
+// stays a runtime spread and keeps `other`'s ecosystem-only fields.
+let mergeInto = (
+  base: Internal.onEventRegistration,
+  ~other: Internal.onEventRegistration,
+): Internal.onEventRegistration => {
+  ...base,
+  contractRegister: other.contractRegister,
+  fieldSelection: Internal.unionFieldSelection(base.fieldSelection, other.fieldSelection),
+}
+
 // Merge each contractRegister into a matching handler registration (either
 // registration order; the merged registration takes the handler's slot so
 // dispatch order follows handler registration order). Two handlers (or two
@@ -188,7 +233,7 @@ let mergeRegistrations = (resolved: array<Internal.onEventRegistration>, ~config
         merged :=
           merged.contents
           ->Array.filterWithIndex((_, j) => j !== i)
-          ->Array.concat([{...reg, contractRegister: target.contractRegister}])
+          ->Array.concat([reg->mergeInto(~other=target)])
       }
     } else {
       // A contractRegister merges into a matching handler registration,
@@ -202,7 +247,7 @@ let mergeRegistrations = (resolved: array<Internal.onEventRegistration>, ~config
       | i =>
         let target = merged.contents->Array.getUnsafe(i)
         let next = merged.contents->Array.copy
-        next->Array.setUnsafe(i, {...target, contractRegister: reg.contractRegister})
+        next->Array.setUnsafe(i, target->mergeInto(~other=reg))
         merged := next
       }
     }
@@ -249,6 +294,27 @@ let addOnEventRegistration = (
 ) => {
   let isWildcard = eventOptions->Option.flatMap(v => v.wildcard)->Option.getOr(false)
   let where = eventOptions->Option.flatMap(v => v.where)
+  // The inline selection doesn't vary by chain: resolve it once here and share
+  // the one value (and its sets) across every chain's registration.
+  let fieldSelection = switch eventOptions->Option.flatMap(v => v.fields) {
+  | None => None
+  | Some(fields) =>
+    // Only EVM resolves a registration selection of its own; Fuel and SVM take
+    // theirs from the event config, so an inline one would be silently dropped.
+    if registration.config.ecosystem.name !== Evm {
+      JsError.throwWithMessage(
+        `The fields option of the "${eventName}" event registration on contract "${contractName}" is only supported on EVM. Select the fields in your config instead.`,
+      )
+    }
+    Some(
+      EventConfigBuilder.resolveInlineFieldSelection(
+        fields,
+        ~contractName,
+        ~eventName,
+        ~enableRawEvents=registration.config.enableRawEvents,
+      ),
+    )
+  }
   let matched = ref(false)
   registration.config.chainMap
   ->ChainMap.values
@@ -268,6 +334,7 @@ let addOnEventRegistration = (
           ~handler,
           ~contractRegister,
           ~where,
+          ~fieldSelection,
           ~startBlock=?contract.startBlock,
         )
         (registration->getChainRegistrations(~chainId=chainConfig.id)).onEventRegistrations
@@ -397,11 +464,47 @@ let getSimulateOnEventRegistrations = (
         ~handler=None,
         ~contractRegister=None,
         ~where=None,
+        ~fieldSelection=None,
       ),
     ]
   }
 }
 
+// An RPC source can only deliver the fields it knows how to parse; the rest are
+// silently skipped at materialisation. Every RPC on the chain counts, whatever
+// it's for — a fallback or realtime source runs the same parsers as a sync one,
+// so a field it can't deliver would go missing for whichever blocks it served.
+// The selection can come from either `config.yaml` or the inline `fields`
+// option, so the message names neither. Runs on the registrations a chain
+// actually keeps, so a handler whose `where` opts out of this chain isn't held
+// to its limits.
+//
+// The `config.yaml` half of this is also rejected at codegen, by the
+// `RpcTransactionField` subenum in `system_config.rs`. That one reports every
+// offending field at once and before the project builds; this one is the only
+// check an inline selection reaches. `RpcFieldSelection_test.res` pins the two
+// to the same field set.
+let validateRpcFieldSelection = (
+  chainConfig: Config.chain,
+  registrations: array<Internal.onEventRegistration>,
+) => {
+  let hasRpc = switch chainConfig.sourceConfig {
+  | EvmSourceConfig({rpcs}) => !(rpcs->Utils.Array.isEmpty)
+  | _ => false
+  }
+  if hasRpc {
+    registrations->Array.forEach(reg =>
+      reg.fieldSelection.transactionFields->Utils.Set.forEach(name =>
+        if !RpcSource.isRpcTransactionField(name) {
+          JsError.throwWithMessage(
+            `The "${name}" transaction field selected for the "${reg.eventConfig.name}" event on contract "${reg.eventConfig.contractName}" is unavailable for indexing via RPC. Remove it from the field selection, or remove chain ${chainConfig.id->ChainId.toString}'s RPC source — even an RPC the chain only falls back to has to deliver the selection.`,
+          )
+        }
+      )
+    )
+  }
+}
+
 let finishRegistration = (~config: Config.t): registrationsByChainId => {
   switch getActiveRegistration() {
   | Some(r) => {
@@ -452,6 +555,7 @@ let finishRegistration = (~config: Config.t): registrationsByChainId => {
                       ~handler=None,
                       ~contractRegister=None,
                       ~where=None,
+                      ~fieldSelection=None,
                       ~startBlock=?contract.startBlock,
                     ),
                   )
@@ -487,6 +591,8 @@ let finishRegistration = (~config: Config.t): registrationsByChainId => {
           }
         })
 
+        validateRpcFieldSelection(chainConfig, onEventRegistrations)
+
         registrationsByChainId->Dict.set(
           key,
           {

package/src/HandlerRegister.res.mjs

@@ -4,6 +4,8 @@ import * as Utils from "./Utils.res.mjs";
 import * as ChainId from "./ChainId.res.mjs";
 import * as Logging from "./Logging.res.mjs";
 import * as ChainMap from "./ChainMap.res.mjs";
+import * as Internal from "./Internal.res.mjs";
+import * as RpcSource from "./sources/RpcSource.res.mjs";
 import * as EnvioGlobal from "./EnvioGlobal.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
@@ -54,6 +56,28 @@ function startRegistration(config) {
   queued.forEach(fn => fn(r));
 }
 
+function makeRegistration(config) {
+  return {
+    config: config,
+    registrationsByChainId: {},
+    finished: false
+  };
+}
+
+async function useRegistration(registration, fn) {
+  let previous = EnvioGlobal.value.activeRegistration;
+  EnvioGlobal.value.activeRegistration = Primitive_option.some(registration);
+  let result;
+  try {
+    result = await fn();
+  } catch (exn) {
+    EnvioGlobal.value.activeRegistration = previous;
+    throw exn;
+  }
+  EnvioGlobal.value.activeRegistration = previous;
+  return result;
+}
+
 function getChainRegistrations(r, chainId) {
   let key = ChainId.toString(chainId);
   let existing = r.registrationsByChainId[key];
@@ -70,11 +94,11 @@ function getChainRegistrations(r, chainId) {
   return fresh;
 }
 
-function buildOnEventRegistrationWith(config, chainId, eventConfig, isWildcard, handler, contractRegister, where, startBlock) {
+function buildOnEventRegistrationWith(config, chainId, eventConfig, isWildcard, handler, contractRegister, where, fieldSelection, startBlock) {
   let match = config.ecosystem.name;
   switch (match) {
     case "evm" :
-      return EventConfigBuilder.buildEvmOnEventRegistration(eventConfig, isWildcard, handler, contractRegister, where, chainId, config.ecosystem.onEventBlockFilterSchema, startBlock);
+      return EventConfigBuilder.buildEvmOnEventRegistration(eventConfig, isWildcard, handler, contractRegister, where, chainId, config.ecosystem.onEventBlockFilterSchema, fieldSelection, startBlock);
     case "fuel" :
       return EventConfigBuilder.buildFuelOnEventRegistration(eventConfig, isWildcard, handler, contractRegister, startBlock);
     case "svm" :
@@ -96,6 +120,13 @@ function sameEventAndFilter(a, b, config) {
   }
 }
 
+function mergeInto(base, other) {
+  let newrecord = {...base};
+  newrecord.fieldSelection = Internal.unionFieldSelection(base.fieldSelection, other.fieldSelection);
+  newrecord.contractRegister = other.contractRegister;
+  return newrecord;
+}
+
 function mergeRegistrations(resolved, config) {
   let merged = {
     contents: []
@@ -114,8 +145,7 @@ function mergeRegistrations(resolved, config) {
         return;
       }
       let target = merged.contents[i];
-      let newrecord = {...reg};
-      merged.contents = merged.contents.filter((param, j) => j !== i).concat([(newrecord.contractRegister = target.contractRegister, newrecord)]);
+      merged.contents = merged.contents.filter((param, j) => j !== i).concat([mergeInto(reg, target)]);
       return;
     }
     let i$1 = merged.contents.findIndex(m => {
@@ -131,9 +161,7 @@ function mergeRegistrations(resolved, config) {
     }
     let target$1 = merged.contents[i$1];
     let next = merged.contents.slice();
-    let newrecord$1 = {...target$1};
-    newrecord$1.contractRegister = reg.contractRegister;
-    next[i$1] = newrecord$1;
+    next[i$1] = mergeInto(target$1, reg);
     merged.contents = next;
   });
   return merged.contents;
@@ -171,6 +199,8 @@ function describeConfigured(registration, contractName) {
 function addOnEventRegistration(registration, contractName, eventName, handler, contractRegister, eventOptions) {
   let isWildcard = Stdlib_Option.getOr(Stdlib_Option.flatMap(eventOptions, v => v.wildcard), false);
   let where = Stdlib_Option.flatMap(eventOptions, v => v.where);
+  let fields = Stdlib_Option.flatMap(eventOptions, v => v.fields);
+  let fieldSelection = fields !== undefined ? (registration.config.ecosystem.name !== "evm" ? Stdlib_JsError.throwWithMessage(`The fields option of the "` + eventName + `" event registration on contract "` + contractName + `" is only supported on EVM. Select the fields in your config instead.`) : undefined, EventConfigBuilder.resolveInlineFieldSelection(fields, contractName, eventName, registration.config.enableRawEvents)) : undefined;
   let matched = {
     contents: false
   };
@@ -184,7 +214,7 @@ function addOnEventRegistration(registration, contractName, eventName, handler,
       return;
     }
     matched.contents = true;
-    let reg = buildOnEventRegistrationWith(registration.config, chainConfig.id, eventConfig, isWildcard, handler, contractRegister, where, contract.startBlock);
+    let reg = buildOnEventRegistrationWith(registration.config, chainConfig.id, eventConfig, isWildcard, handler, contractRegister, where, fieldSelection, contract.startBlock);
     getChainRegistrations(registration, chainConfig.id).onEventRegistrations.push(reg);
   });
   if (matched.contents) {
@@ -257,7 +287,23 @@ function getSimulateOnEventRegistrations(config, chainId, eventConfig) {
   if (Utils.$$Array.notEmpty(matching)) {
     return matching;
   } else {
-    return [buildOnEventRegistrationWith(config, chainId, eventConfig, false, undefined, undefined, undefined, undefined)];
+    return [buildOnEventRegistrationWith(config, chainId, eventConfig, false, undefined, undefined, undefined, undefined, undefined)];
+  }
+}
+
+function validateRpcFieldSelection(chainConfig, registrations) {
+  let match = chainConfig.sourceConfig;
+  let hasRpc;
+  hasRpc = match.TAG === "EvmSourceConfig" ? !Utils.$$Array.isEmpty(match.rpcs) : false;
+  if (hasRpc) {
+    registrations.forEach(reg => {
+      reg.fieldSelection.transactionFields.forEach(name => {
+        if (!RpcSource.isRpcTransactionField(name)) {
+          return Stdlib_JsError.throwWithMessage(`The "` + name + `" transaction field selected for the "` + reg.eventConfig.name + `" event on contract "` + reg.eventConfig.contractName + `" is unavailable for indexing via RPC. Remove it from the field selection, or remove chain ` + ChainId.toString(chainConfig.id) + `'s RPC source — even an RPC the chain only falls back to has to deliver the selection.`);
+        }
+      });
+    });
+    return;
   }
 }
 
@@ -284,7 +330,7 @@ function finishRegistration(config) {
           return;
         }
         if (config.enableRawEvents) {
-          rawEventRegs.push(buildOnEventRegistrationWith(config, chainId, eventConfig, false, undefined, undefined, undefined, contract.startBlock));
+          rawEventRegs.push(buildOnEventRegistrationWith(config, chainId, eventConfig, false, undefined, undefined, undefined, undefined, contract.startBlock));
           return;
         }
         let set = notRegisteredEventsByContract[contract.name];
@@ -307,6 +353,7 @@ function finishRegistration(config) {
       let newrecord = {...reg};
       onEventRegistrations.push((newrecord.index = onEventRegistrations.length, newrecord));
     });
+    validateRpcFieldSelection(chainConfig, onEventRegistrations);
     let chainRegs = r.registrationsByChainId[key];
     registrationsByChainId[key] = {
       onEventRegistrations: onEventRegistrations,
@@ -435,6 +482,8 @@ function registerOnBlock(name, where, handler, getChainsObject) {
 
 export {
   startRegistration,
+  makeRegistration,
+  useRegistration,
   resetOnEventRegistrations,
   isPendingRegistration,
   finishRegistration,

package/src/HandlerRegister.resi

@@ -5,6 +5,10 @@ type chainRegistrations = {
 type registrationsByChainId = dict<chainRegistrations>
 
 let startRegistration: (~config: Config.t) => unit
+
+type registration
+let makeRegistration: (~config: Config.t) => registration
+let useRegistration: (registration, unit => promise<'a>) => promise<'a>
 let resetOnEventRegistrations: unit => unit
 let isPendingRegistration: unit => bool
 let finishRegistration: (~config: Config.t) => registrationsByChainId

package/src/Internal.res

@@ -140,7 +140,7 @@ let evmTransactionFieldSchema = S.enum(allEvmTransactionFields)
 // position in the selection mask) and `Svm.res` `transactionFields`.
 type svmTransactionField =
   | @as("transactionIndex") TransactionIndex
-  | @as("signatures") Signatures
+  | @as("signature") Signature
   | @as("feePayer") FeePayer
   | @as("success") Success
   | @as("err") Err
@@ -150,10 +150,11 @@ type svmTransactionField =
   | @as("recentBlockhash") RecentBlockhash
   | @as("version") Version
   | @as("tokenBalances") TokenBalances
+  | @as("allSignatures") AllSignatures
 
 let allSvmTransactionFields: array<svmTransactionField> = [
   TransactionIndex,
-  Signatures,
+  Signature,
   FeePayer,
   Success,
   Err,
@@ -163,6 +164,7 @@ let allSvmTransactionFields: array<svmTransactionField> = [
   RecentBlockhash,
   Version,
   TokenBalances,
+  AllSignatures,
 ]
 let svmTransactionFieldSchema = S.enum(allSvmTransactionFields)
 
@@ -416,6 +418,51 @@ type indexingContract = {
   effectiveStartBlock: int,
 }
 
+// What a single registration fetches and materialises. Field names are strings
+// so every ecosystem shares one type — the typed field variants are strings at
+// runtime. Always built through `makeFieldSelection`/`unionFieldSelection`
+// below, so a set and its mask are never derived from different inputs. Unlike
+// `eventConfig`, not `private` — that would block those two constructors too,
+// since a private record can only be coerced from a distinct record type.
+type fieldSelection = {
+  blockFields: Utils.Set.t<string>,
+  transactionFields: Utils.Set.t<string>,
+  // The sets precompiled to the store selections `ChainState` materialises with.
+  blockMask: float,
+  transactionMask: float,
+}
+
+// `~blockMaskFn`/`~transactionMaskFn` are the ecosystem's `Evm`/`Svm`/`Fuel`
+// mask functions, which the ecosystem modules pass in (they depend on this
+// module, so it can't reach them).
+let makeFieldSelection = (
+  ~blockFields: Utils.Set.t<string>,
+  ~transactionFields: Utils.Set.t<string>,
+  ~blockMaskFn: Utils.Set.t<string> => float,
+  ~transactionMaskFn: Utils.Set.t<string> => float,
+): fieldSelection => {
+  blockFields,
+  transactionFields,
+  blockMask: blockMaskFn(blockFields),
+  transactionMask: transactionMaskFn(transactionFields),
+}
+
+// Two registrations merged into one dispatch off a single item, so it has to
+// carry the union of what both callbacks read. Each callback's type only claims
+// its own selection, so the extra fields are unread rather than unsound.
+//
+// The overwhelmingly common case is two registrations that never named fields
+// inline and so share their event config's sets by reference — returning those
+// unchanged keeps the merge allocation-free.
+let unionFields = (a, b) => a === b ? a : a->Utils.Set.union(b)
+
+let unionFieldSelection = (a: fieldSelection, b: fieldSelection): fieldSelection => {
+  blockFields: unionFields(a.blockFields, b.blockFields),
+  transactionFields: unionFields(a.transactionFields, b.transactionFields),
+  blockMask: FieldMask.orMask(a.blockMask, b.blockMask),
+  transactionMask: FieldMask.orMask(a.transactionMask, b.transactionMask),
+}
+
 // Definition of an event/instruction we know how to decode: identity + decode
 // schemas + chain-independent field selection. A pure function of the ABI +
 // config, shared across chains. `private` so it can only be coerced from an
@@ -427,22 +474,12 @@ type eventConfig = private {
   contractName: string,
   paramsRawEventSchema: S.schema<eventParams>,
   simulateParamsSchema: S.schema<eventParams>,
-  // Field names selected for the chain's transaction-store materialisation
-  // (camelCase, matching the ecosystem's `transactionFields`). Stored as a
-  // string set so the shared mask logic is ecosystem-agnostic; sources recover
-  // the typed view where they need it.
-  selectedTransactionFields: Utils.Set.t<string>,
-  // `selectedTransactionFields` precompiled to the transaction-store selection
-  // bitmask (bit per ecosystem field code). Materialisation reads this per item
-  // so each transaction decodes only the fields its event selected. `0.` when
-  // nothing is selected or the ecosystem carries the transaction inline (Fuel).
-  transactionFieldMask: float,
-  // Selected block fields precompiled to the block-store selection bitmask (bit
-  // per ecosystem field code). `0.` for ecosystems that carry the block fully
-  // inline (RPC/Fuel). The EVM selection always includes number/timestamp/hash,
-  // so an EVM mask always has their bits set; SVM stamps slot/time/hash inline
-  // from the response and its mask is the user's selection alone.
-  blockFieldMask: float,
+  // The `config.yaml` selection, which every registration of this event
+  // inherits unless it names its own fields inline. Held by reference, so two
+  // un-customized registrations share one set — which is what keeps a merge
+  // allocation-free and the per-source parser caches (keyed on set identity)
+  // effective.
+  fieldSelection: fieldSelection,
 }
 
 type fuelEventKind =
@@ -497,7 +534,6 @@ type onEventWhereArgs<'chain> = {chain: 'chain}
 
 type evmEventConfig = {
   ...eventConfig,
-  selectedBlockFields: Utils.Set.t<evmBlockField>,
   sighash: string,
   topicCount: int,
   paramsMetadata: array<paramMeta>,
@@ -525,10 +561,6 @@ type svmAccountFilterGroup = array<svmAccountFilter>
 
 type svmInstructionEventConfig = {
   ...eventConfig,
-  /** Block fields selected via `field_selection.block_fields` (`slot` is always
-   included and excluded from this set). Drives the block query columns;
-   precompiled to `blockFieldMask` for store materialisation. */
-  selectedBlockFields: Utils.Set.t<svmBlockField>,
   /** Base58 Solana program id this instruction belongs to. */
   programId: SvmTypes.Pubkey.t,
   /** Hex-encoded discriminator. `None` matches every instruction in the program. */
@@ -589,6 +621,10 @@ type onEventRegistration = {
   // Final start block: the contract/chain config value, overridden by a
   // `where.block.number._gte` when the registered `where` supplies one.
   startBlock: option<int>,
+  // The `eventConfig` selection unless the registration passed an inline
+  // `fields` option, which replaces it. Two registrations of one event can
+  // select different fields, so this is per-registration rather than shared.
+  fieldSelection: fieldSelection,
 }
 
 type evmOnEventRegistration = {
@@ -625,6 +661,7 @@ type eventItem = private {
   chainId: ChainId.t,
   blockNumber: int,
   logIndex: int,
+  orderPath?: array<int>,
   // Within-block transaction index — the key into the per-chain transaction
   // store. Unused (0) for ecosystems that carry the transaction inline (Fuel).
   transactionIndex: int,
@@ -678,17 +715,31 @@ type item =
       chainId: ChainId.t,
       blockNumber: int,
       logIndex: int,
+      // Ordering tiebreak for ecosystems whose within-block order isn't a
+      // scalar. SVM keys an instruction by `(transactionIndex, path)`: the
+      // logIndex above is the transaction, this is its position in that
+      // transaction's CPI tree. Absent on EVM and Fuel, whose log/receipt
+      // index already totally orders a block.
+      orderPath?: array<int>,
       transactionIndex: int,
       payload: eventPayload,
     })
-  | @as(1) Block({onBlockRegistration: onBlockRegistration, blockNumber: int, logIndex: int})
+  | @as(1) Block({onBlockRegistration: onBlockRegistration, blockNumber: int})
 
 external castUnsafeEventItem: item => eventItem = "%identity"
 
 @get
 external getItemBlockNumber: item => int = "blockNumber"
+// Only meaningful on an `Event`: a block item has no log index, and the buffer
+// comparator reads this only after the kinds match.
 @get
 external getItemLogIndex: item => int = "logIndex"
+@get
+external getItemOrderPath: item => Nullable.t<array<int>> = "orderPath"
+// The variant tag. Read directly so the comparator can order every event of a
+// block ahead of that block's handlers without a `switch`.
+@get
+external getItemKind: item => int = "kind"
 
 let getItemChainId = item =>
   switch item {
@@ -696,9 +747,18 @@ let getItemChainId = item =>
   | Block({onBlockRegistration: {chainId}}) => chainId
   }
 
+// The `fields` option of an EVM `onEvent`/`contractRegister` registration:
+// the block and transaction fields the handler reads. Replaces the config
+// `field_selection` for this registration.
+type evmFieldsSelection = {
+  block?: array<string>,
+  transaction?: array<string>,
+}
+
 type eventOptions<'where> = {
   wildcard?: bool,
   where?: 'where,
+  fields?: evmFieldsSelection,
 }
 
 type fuelSupplyParams = {

package/src/Internal.res.mjs

@@ -4,6 +4,7 @@ import * as Table from "./db/Table.res.mjs";
 import * as Utils from "./Utils.res.mjs";
 import * as Address from "./Address.res.mjs";
 import * as ChainId from "./ChainId.res.mjs";
+import * as FieldMask from "./sources/FieldMask.res.mjs";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
 
@@ -78,7 +79,7 @@ let evmTransactionFieldSchema = S$RescriptSchema.$$enum(allEvmTransactionFields)
 
 let allSvmTransactionFields = [
   "transactionIndex",
-  "signatures",
+  "signature",
   "feePayer",
   "success",
   "err",
@@ -87,7 +88,8 @@ let allSvmTransactionFields = [
   "accountKeys",
   "recentBlockhash",
   "version",
-  "tokenBalances"
+  "tokenBalances",
+  "allSignatures"
 ];
 
 let svmTransactionFieldSchema = S$RescriptSchema.$$enum(allSvmTransactionFields);
@@ -139,6 +141,32 @@ let evmNullableTransactionFields = new Set([
   "type"
 ]);
 
+function makeFieldSelection(blockFields, transactionFields, blockMaskFn, transactionMaskFn) {
+  return {
+    blockFields: blockFields,
+    transactionFields: transactionFields,
+    blockMask: blockMaskFn(blockFields),
+    transactionMask: transactionMaskFn(transactionFields)
+  };
+}
+
+function unionFields(a, b) {
+  if (a === b) {
+    return a;
+  } else {
+    return a.union(b);
+  }
+}
+
+function unionFieldSelection(a, b) {
+  return {
+    blockFields: unionFields(a.blockFields, b.blockFields),
+    transactionFields: unionFields(a.transactionFields, b.transactionFields),
+    blockMask: FieldMask.orMask(a.blockMask, b.blockMask),
+    transactionMask: FieldMask.orMask(a.transactionMask, b.transactionMask)
+  };
+}
+
 function dependsOnAddresses(isWildcard, filterByAddresses) {
   if (isWildcard) {
     return filterByAddresses;
@@ -306,6 +334,9 @@ export {
   svmBlockFieldSchema,
   evmNullableBlockFields,
   evmNullableTransactionFields,
+  makeFieldSelection,
+  unionFields,
+  unionFieldSelection,
   dependsOnAddresses,
   getItemChainId,
   fuelSupplyParamsSchema,

package/src/LazyLoader.res

@@ -58,6 +58,17 @@ let timeoutAfter = timeoutMillis =>
     )
   )
 
+// Remember `k` as cached, evicting the oldest entry once the cache is full.
+let rememberLoaded = (am: asyncMap<'key, 'value>, k: 'key) => {
+  if am.loadedKeys->SDSL.Queue.push(k) > am._cacheSize {
+    switch am.loadedKeys->SDSL.Queue.pop {
+    | None => ()
+    | Some(old) =>
+      let _ = am.externalPromises->Utils.Map.delete(old)
+    }
+  }
+}
+
 let rec loadNext = async (am: asyncMap<'key, 'value>, k: 'key) => {
   // Track that we are loading it now
   let _ = am.inProgress->Utils.Set.add(k)
@@ -75,17 +86,7 @@ let rec loadNext = async (am: asyncMap<'key, 'value>, k: 'key) => {
     // Track that it is no longer in progress
     let _ = am.inProgress->Utils.Set.delete(k)
 
-    // Track that we've loaded this key
-    let loadedKeysNumber = am.loadedKeys->SDSL.Queue.push(k)
-
-    // Delete the oldest key if the cache is overly full
-    if loadedKeysNumber > am._cacheSize {
-      switch am.loadedKeys->SDSL.Queue.pop {
-      | None => ()
-      | Some(old) =>
-        let _ = am.externalPromises->Utils.Map.delete(old)
-      }
-    }
+    am->rememberLoaded(k)
 
     // Load the next one, if there is anything in the queue
     switch am.loaderQueue->SDSL.Queue.pop {