envio 3.3.0-alpha.1 → 3.3.0-alpha.10

package/src/sources/Evm.res

@@ -1,5 +1,7 @@
 // EVM's concrete item payload. Erased to `Internal.eventPayload` on the item
-// and recovered here via `toPayload`.
+// and recovered here via `toPayload`. HyperSync omits `transaction` (it lives
+// raw in the per-chain store and is written onto the payload at batch prep);
+// RPC/simulate build it inline.
 type payload = {
   contractName: string,
   eventName: string,
@@ -7,12 +9,62 @@ type payload = {
   chainId: int,
   srcAddress: Address.t,
   logIndex: int,
-  transaction: Internal.eventTransaction,
-  block: Internal.eventBlock,
+  transaction?: Internal.eventTransaction,
+  // HyperSync omits `block` (it lives raw in the per-chain store and is written
+  // onto the payload at batch prep); RPC/simulate build it inline.
+  block?: Internal.eventBlock,
 }
 external fromPayload: payload => Internal.eventPayload = "%identity"
 external toPayload: Internal.eventPayload => payload = "%identity"
 
+// Ordered transaction field names, the field codes shared with the Rust store
+// (`EvmTxField`). Derived from the typed field list so the two can't drift;
+// `Internal.allEvmTransactionFields` is pinned to the Rust ordinal order by a test.
+let transactionFields =
+  Internal.allEvmTransactionFields->(
+    Utils.magic: array<Internal.evmTransactionField> => array<string>
+  )
+
+// One event's selected transaction fields → store selection bitmask. Computed
+// per event at config build and cached on the event config.
+let eventTransactionFieldMask = TransactionStore.makeMaskFn(transactionFields)
+
+// Ordered block field names. The index of each is the field code shared with the
+// Rust store (`EvmBlockField`) — keep this order in sync.
+let blockFields = [
+  "number",
+  "timestamp",
+  "hash",
+  "parentHash",
+  "nonce",
+  "sha3Uncles",
+  "logsBloom",
+  "transactionsRoot",
+  "stateRoot",
+  "receiptsRoot",
+  "miner",
+  "difficulty",
+  "totalDifficulty",
+  "extraData",
+  "size",
+  "gasLimit",
+  "gasUsed",
+  "uncles",
+  "baseFeePerGas",
+  "blobGasUsed",
+  "excessBlobGas",
+  "parentBeaconBlockRoot",
+  "withdrawalsRoot",
+  "l1BlockNumber",
+  "sendCount",
+  "sendRoot",
+  "mixHash",
+]
+
+// One event's selected block fields → store selection bitmask. Computed per
+// event at config build and cached on the event config.
+let eventBlockFieldMask = BlockStore.makeMaskFn(blockFields)
+
 let cleanUpRawEventFieldsInPlace: JSON.t => unit = %raw(`fields => {
     delete fields.hash
     delete fields.number
@@ -21,70 +73,6 @@ let cleanUpRawEventFieldsInPlace: JSON.t => unit = %raw(`fields => {
 
 let make = (~logger: Pino.t): Ecosystem.t => {
   name: Evm,
-  blockFields: [
-    "number",
-    "timestamp",
-    "hash",
-    "parentHash",
-    "nonce",
-    "sha3Uncles",
-    "logsBloom",
-    "transactionsRoot",
-    "stateRoot",
-    "receiptsRoot",
-    "miner",
-    "difficulty",
-    "totalDifficulty",
-    "extraData",
-    "size",
-    "gasLimit",
-    "gasUsed",
-    "uncles",
-    "baseFeePerGas",
-    "blobGasUsed",
-    "excessBlobGas",
-    "parentBeaconBlockRoot",
-    "withdrawalsRoot",
-    "l1BlockNumber",
-    "sendCount",
-    "sendRoot",
-    "mixHash",
-  ],
-  transactionFields: [
-    "transactionIndex",
-    "hash",
-    "from",
-    "to",
-    "gas",
-    "gasPrice",
-    "maxPriorityFeePerGas",
-    "maxFeePerGas",
-    "cumulativeGasUsed",
-    "effectiveGasPrice",
-    "gasUsed",
-    "input",
-    "nonce",
-    "value",
-    "v",
-    "r",
-    "s",
-    "contractAddress",
-    "logsBloom",
-    "root",
-    "status",
-    "yParity",
-    "chainId",
-    "maxFeePerBlobGas",
-    "blobVersionedHashes",
-    "type",
-    "l1Fee",
-    "l1GasPrice",
-    "l1GasUsed",
-    "l1FeeScalar",
-    "gasUsedForL1",
-    "accessList",
-    "authorizationList",
-  ],
   blockNumberName: "number",
   blockTimestampName: "timestamp",
   blockHashName: "hash",
@@ -102,17 +90,22 @@ let make = (~logger: Pino.t): Ecosystem.t => {
   // range chunk is validated by `eventBlockRangeSchema` in
   // `LogSelection.res` which rejects `_lte`/`_every` (use `onBlock` for
   // stride- and endBlock-based block handlers).
+  // `S.strict` on the inner object rejects unknown `block` fields (e.g. a
+  // `numbre` typo or `block: {timestamp: ...}`) instead of silently
+  // ignoring them.
   onEventBlockFilterSchema: S.object(s =>
-    s.field("block", S.option(S.object(s2 => s2.field("number", S.unknown))))
+    s.field("block", S.option(S.object(s2 => s2.field("number", S.unknown))->S.strict))
   ),
   logger,
-  toEvent: eventItem => eventItem.payload->Internal.payloadToEvent,
+  // The payload carries `transaction` by batch prep (HyperSync) or inline
+  // (RPC/simulate), so the event is the payload as-is.
+  toEvent: eventItem => eventItem.payload->(Utils.magic: Internal.eventPayload => Internal.event),
   toEventLogger: eventItem =>
     Logging.createChildFrom(
       ~logger,
       ~params={
-        "contract": eventItem.eventConfig.contractName,
-        "event": eventItem.eventConfig.name,
+        "contract": eventItem.onEventRegistration.eventConfig.contractName,
+        "event": eventItem.onEventRegistration.eventConfig.name,
         "chainId": eventItem.chain->ChainMap.Chain.toChainId,
         "block": eventItem.blockNumber,
         "logIndex": eventItem.logIndex,
@@ -121,11 +114,29 @@ let make = (~logger: Pino.t): Ecosystem.t => {
     ),
   toRawEvent: eventItem => {
     let payload = eventItem.payload->toPayload
+    let eventConfig =
+      eventItem.onEventRegistration.eventConfig->(
+        Utils.magic: Internal.eventConfig => Internal.evmEventConfig
+      )
+    // Store-backed payloads get `block` written at batch prep and inline
+    // sources carry it from the start, with hash/timestamp always selected —
+    // so both are present by the time a raw event is built.
+    let header = switch payload.block {
+    | Some(block) => block->(Utils.magic: Internal.eventBlock => {"hash": string, "timestamp": int})
+    | None =>
+      JsError.throwWithMessage("Unexpected case: The event block is missing for a raw event")
+    }
     eventItem->RawEvent.make(
       ~block=payload.block,
       ~transaction=payload.transaction,
-      ~params=payload.params,
+      // The decoder emits `{}` for zero-parameter events, which the params
+      // schema rejects; pass unit so it serializes to the "null" sentinel.
+      ~params=eventConfig.paramsMetadata->Array.length == 0
+        ? ()->(Utils.magic: unit => Internal.eventParams)
+        : payload.params,
       ~srcAddress=payload.srcAddress,
+      ~blockHash=header["hash"],
+      ~blockTimestamp=header["timestamp"],
       ~cleanUpRawEventFieldsInPlace,
     )
   },

package/src/sources/Evm.res.mjs

@@ -1,8 +1,47 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Logging from "../Logging.res.mjs";
+import * as Internal from "../Internal.res.mjs";
 import * as RawEvent from "../RawEvent.res.mjs";
+import * as BlockStore from "./BlockStore.res.mjs";
+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 TransactionStore from "./TransactionStore.res.mjs";
+
+let eventTransactionFieldMask = TransactionStore.makeMaskFn(Internal.allEvmTransactionFields);
+
+let blockFields = [
+  "number",
+  "timestamp",
+  "hash",
+  "parentHash",
+  "nonce",
+  "sha3Uncles",
+  "logsBloom",
+  "transactionsRoot",
+  "stateRoot",
+  "receiptsRoot",
+  "miner",
+  "difficulty",
+  "totalDifficulty",
+  "extraData",
+  "size",
+  "gasLimit",
+  "gasUsed",
+  "uncles",
+  "baseFeePerGas",
+  "blobGasUsed",
+  "excessBlobGas",
+  "parentBeaconBlockRoot",
+  "withdrawalsRoot",
+  "l1BlockNumber",
+  "sendCount",
+  "sendRoot",
+  "mixHash"
+];
+
+let eventBlockFieldMask = BlockStore.makeMaskFn(blockFields);
 
 let cleanUpRawEventFieldsInPlace = (fields => {
     delete fields.hash
@@ -13,82 +52,18 @@ let cleanUpRawEventFieldsInPlace = (fields => {
 function make(logger) {
   return {
     name: "evm",
-    blockFields: [
-      "number",
-      "timestamp",
-      "hash",
-      "parentHash",
-      "nonce",
-      "sha3Uncles",
-      "logsBloom",
-      "transactionsRoot",
-      "stateRoot",
-      "receiptsRoot",
-      "miner",
-      "difficulty",
-      "totalDifficulty",
-      "extraData",
-      "size",
-      "gasLimit",
-      "gasUsed",
-      "uncles",
-      "baseFeePerGas",
-      "blobGasUsed",
-      "excessBlobGas",
-      "parentBeaconBlockRoot",
-      "withdrawalsRoot",
-      "l1BlockNumber",
-      "sendCount",
-      "sendRoot",
-      "mixHash"
-    ],
-    transactionFields: [
-      "transactionIndex",
-      "hash",
-      "from",
-      "to",
-      "gas",
-      "gasPrice",
-      "maxPriorityFeePerGas",
-      "maxFeePerGas",
-      "cumulativeGasUsed",
-      "effectiveGasPrice",
-      "gasUsed",
-      "input",
-      "nonce",
-      "value",
-      "v",
-      "r",
-      "s",
-      "contractAddress",
-      "logsBloom",
-      "root",
-      "status",
-      "yParity",
-      "chainId",
-      "maxFeePerBlobGas",
-      "blobVersionedHashes",
-      "type",
-      "l1Fee",
-      "l1GasPrice",
-      "l1GasUsed",
-      "l1FeeScalar",
-      "gasUsedForL1",
-      "accessList",
-      "authorizationList"
-    ],
     blockNumberName: "number",
     blockTimestampName: "timestamp",
     blockHashName: "hash",
     cleanUpRawEventFieldsInPlace: cleanUpRawEventFieldsInPlace,
     onBlockMethodName: "onBlock",
     onBlockFilterSchema: S$RescriptSchema.object(s => s.f("block", S$RescriptSchema.option(S$RescriptSchema.object(s2 => s2.f("number", S$RescriptSchema.unknown))))),
-    onEventBlockFilterSchema: S$RescriptSchema.object(s => s.f("block", S$RescriptSchema.option(S$RescriptSchema.object(s2 => s2.f("number", S$RescriptSchema.unknown))))),
+    onEventBlockFilterSchema: S$RescriptSchema.object(s => s.f("block", S$RescriptSchema.option(S$RescriptSchema.strict(S$RescriptSchema.object(s2 => s2.f("number", S$RescriptSchema.unknown)))))),
     logger: logger,
     toEvent: eventItem => eventItem.payload,
     toEventLogger: eventItem => Logging.createChildFrom(logger, {
-      contract: eventItem.eventConfig.contractName,
-      event: eventItem.eventConfig.name,
+      contract: eventItem.onEventRegistration.eventConfig.contractName,
+      event: eventItem.onEventRegistration.eventConfig.name,
       chainId: eventItem.chain,
       block: eventItem.blockNumber,
       logIndex: eventItem.logIndex,
@@ -96,13 +71,22 @@ function make(logger) {
     }),
     toRawEvent: eventItem => {
       let payload = eventItem.payload;
-      return RawEvent.make(eventItem, payload.block, payload.transaction, payload.params, payload.srcAddress, cleanUpRawEventFieldsInPlace);
+      let eventConfig = eventItem.onEventRegistration.eventConfig;
+      let block = payload.block;
+      let header = block !== undefined ? Primitive_option.valFromOption(block) : Stdlib_JsError.throwWithMessage("Unexpected case: The event block is missing for a raw event");
+      return RawEvent.make(eventItem, payload.block, payload.transaction, eventConfig.paramsMetadata.length === 0 ? undefined : payload.params, payload.srcAddress, header.hash, header.timestamp, cleanUpRawEventFieldsInPlace);
     }
   };
 }
 
+let transactionFields = Internal.allEvmTransactionFields;
+
 export {
+  transactionFields,
+  eventTransactionFieldMask,
+  blockFields,
+  eventBlockFieldMask,
   cleanUpRawEventFieldsInPlace,
   make,
 }
-/* Logging Not a pure module */
+/* eventTransactionFieldMask Not a pure module */

package/src/sources/EvmChain.res

@@ -3,6 +3,7 @@ type rpc = {
   sourceFor: Source.sourceFor,
   syncConfig?: Config.sourceSyncOptions,
   ws?: string,
+  headers?: dict<string>,
 }
 
 let getSyncConfig = (
@@ -31,46 +32,42 @@ let getSyncConfig = (
     intervalCeiling: Env.Configurable.SyncConfig.intervalCeiling->Option.getOr(
       intervalCeiling->Option.getOr(10_000),
     ),
-    backoffMillis: backoffMillis->Option.getOr(5000),
+    backoffMillis: backoffMillis->Option.getOr(2000),
     queryTimeoutMillis,
     fallbackStallTimeout: fallbackStallTimeout->Option.getOr(queryTimeoutMillis / 2),
     pollingInterval: pollingInterval->Option.getOr(1000),
   }
 }
 
-let collectEventParams = (contracts: array<Internal.evmContractConfig>): array<
+let collectEventParams = (onEventRegistrations: array<Internal.evmOnEventRegistration>): array<
   HyperSyncClient.Decoder.eventParamsInput,
 > => {
   let result = []
-  contracts->Array.forEach(contract => {
-    contract.events->Array.forEach(event => {
-      result
-      ->Array.push({
-        HyperSyncClient.Decoder.sighash: event.sighash,
-        topicCount: event.topicCount,
-        eventName: event.name,
-        contractName: contract.name,
-        params: event.paramsMetadata,
-      })
-      ->ignore
+  onEventRegistrations->Array.forEach(reg => {
+    let event = reg.eventConfig->(Utils.magic: Internal.eventConfig => Internal.evmEventConfig)
+    result
+    ->Array.push({
+      HyperSyncClient.Decoder.sighash: event.sighash,
+      topicCount: event.topicCount,
+      eventName: event.name,
+      contractName: event.contractName,
+      params: event.paramsMetadata,
     })
+    ->ignore
   })
   result
 }
 
 let makeSources = (
   ~chain,
-  ~contracts: array<Internal.evmContractConfig>,
+  ~onEventRegistrations: array<Internal.evmOnEventRegistration>,
   ~hyperSync,
   ~rpcs: array<rpc>,
   ~lowercaseAddresses,
 ) => {
-  let eventRouter =
-    contracts
-    ->Array.flatMap(contract => contract.events)
-    ->EventRouter.fromEvmEventModsOrThrow(~chain)
+  let eventRouter = onEventRegistrations->EventRouter.fromEvmEventModsOrThrow(~chain)
 
-  let allEventParams = collectEventParams(contracts)
+  let allEventParams = collectEventParams(onEventRegistrations)
 
   let sources = switch hyperSync {
   | Some(endpointUrl) => [
@@ -89,7 +86,7 @@ let makeSources = (
     ]
   | _ => []
   }
-  rpcs->Array.forEach(({?syncConfig, url, sourceFor, ?ws}) => {
+  rpcs->Array.forEach(({?syncConfig, url, sourceFor, ?ws, ?headers}) => {
     let source = RpcSource.make({
       chain,
       sourceFor,
@@ -99,6 +96,7 @@ let makeSources = (
       allEventParams,
       lowercaseAddresses,
       ?ws,
+      ?headers,
     })
     let _ = sources->Array.push(source)
   })

package/src/sources/EvmChain.res.mjs

@@ -13,32 +13,31 @@ function getSyncConfig(param) {
     backoffMultiplicative: Stdlib_Option.getOr(Env.Configurable.SyncConfig.backoffMultiplicative, Stdlib_Option.getOr(param.backoffMultiplicative, 0.8)),
     accelerationAdditive: Stdlib_Option.getOr(Env.Configurable.SyncConfig.accelerationAdditive, Stdlib_Option.getOr(param.accelerationAdditive, 500)),
     intervalCeiling: Stdlib_Option.getOr(Env.Configurable.SyncConfig.intervalCeiling, Stdlib_Option.getOr(param.intervalCeiling, 10000)),
-    backoffMillis: Stdlib_Option.getOr(param.backoffMillis, 5000),
+    backoffMillis: Stdlib_Option.getOr(param.backoffMillis, 2000),
     queryTimeoutMillis: queryTimeoutMillis,
     fallbackStallTimeout: Stdlib_Option.getOr(param.fallbackStallTimeout, queryTimeoutMillis / 2 | 0),
     pollingInterval: Stdlib_Option.getOr(param.pollingInterval, 1000)
   };
 }
 
-function collectEventParams(contracts) {
+function collectEventParams(onEventRegistrations) {
   let result = [];
-  contracts.forEach(contract => {
-    contract.events.forEach(event => {
-      result.push({
-        sighash: event.sighash,
-        topicCount: event.topicCount,
-        eventName: event.name,
-        contractName: contract.name,
-        params: event.paramsMetadata
-      });
+  onEventRegistrations.forEach(reg => {
+    let event = reg.eventConfig;
+    result.push({
+      sighash: event.sighash,
+      topicCount: event.topicCount,
+      eventName: event.name,
+      contractName: event.contractName,
+      params: event.paramsMetadata
     });
   });
   return result;
 }
 
-function makeSources(chain, contracts, hyperSync, rpcs, lowercaseAddresses) {
-  let eventRouter = EventRouter.fromEvmEventModsOrThrow(contracts.flatMap(contract => contract.events), chain);
-  let allEventParams = collectEventParams(contracts);
+function makeSources(chain, onEventRegistrations, hyperSync, rpcs, lowercaseAddresses) {
+  let eventRouter = EventRouter.fromEvmEventModsOrThrow(onEventRegistrations, chain);
+  let allEventParams = collectEventParams(onEventRegistrations);
   let sources = hyperSync !== undefined ? [HyperSyncSource.make({
         chain: chain,
         endpointUrl: hyperSync,
@@ -60,7 +59,8 @@ function makeSources(chain, contracts, hyperSync, rpcs, lowercaseAddresses) {
       eventRouter: eventRouter,
       allEventParams: allEventParams,
       lowercaseAddresses: lowercaseAddresses,
-      ws: param.ws
+      ws: param.ws,
+      headers: param.headers
     });
     sources.push(source);
   });

package/src/sources/EvmRpcClient.res

@@ -1,9 +1,56 @@
-type cfg = {url: string, httpReqTimeoutMillis?: int}
+type cfg = {
+  url: string,
+  httpReqTimeoutMillis?: int,
+  headers?: dict<string>,
+  initialBlockInterval: int,
+  backoffMultiplicative: float,
+  accelerationAdditive: int,
+  intervalCeiling: int,
+  backoffMillis: int,
+  queryTimeoutMillis: int,
+}
+
+// Decoded `params` keyed by contract name, matching the HyperSync decoder's
+// shape so the caller routes by address then picks its contract's params.
+type rpcEventItem = {
+  log: Rpc.GetLogs.log,
+  params: Nullable.t<dict<Internal.eventParams>>,
+}
+
+// `addresses` omitted matches any address (a wildcard selection). Each `topics`
+// position is `null` (match any) or a list of accepted topic hashes; the
+// single-match case is a one-element list.
+type logSelectionInput = {
+  addresses?: array<Address.t>,
+  topics: array<Nullable.t<array<string>>>,
+}
 
-type t = {getHeight: unit => promise<int>}
+type nextPageParams = {
+  fromBlock: int,
+  toBlockCeiling: int,
+  logSelections: array<logSelectionInput>,
+  partitionId: string,
+}
+
+type nextPageResponse = {
+  items: array<rpcEventItem>,
+  toBlock: int,
+  requestStats: array<Source.requestStat>,
+}
+
+// The caller provides a range; Rust decides the actual `toBlock` and returns it.
+type t = {
+  getHeight: unit => promise<int>,
+  getNextPage: nextPageParams => promise<nextPageResponse>,
+}
 
 @send
-external classNew: (Core.evmRpcClientCtor, cfg) => t = "new"
+external classNew: (
+  Core.evmRpcClientCtor,
+  cfg,
+  array<HyperSyncClient.Decoder.eventParamsInput>,
+  ~checksumAddresses: bool,
+) => t = "new"
 
 // Rust encodes JSON-RPC errors as a JSON payload in the napi error's
 // message: `{"kind":"JsonRpcError","code":-32005,"message":"..."}`.
@@ -34,9 +81,31 @@ let coerceErrorOrThrow = exn =>
   | None => exn->throw
   }
 
-let make = (~url, ~httpReqTimeoutMillis=?) => {
-  let client = Core.getAddon().evmRpcClient->classNew({url, ?httpReqTimeoutMillis})
+let make = (
+  ~url,
+  ~checksumAddresses,
+  ~syncConfig: Config.sourceSync,
+  ~httpReqTimeoutMillis=?,
+  ~headers=?,
+  ~allEventParams=[],
+) => {
+  let client = Core.getAddon().evmRpcClient->classNew(
+    {
+      url,
+      ?httpReqTimeoutMillis,
+      ?headers,
+      initialBlockInterval: syncConfig.initialBlockInterval,
+      backoffMultiplicative: syncConfig.backoffMultiplicative,
+      accelerationAdditive: syncConfig.accelerationAdditive,
+      intervalCeiling: syncConfig.intervalCeiling,
+      backoffMillis: syncConfig.backoffMillis,
+      queryTimeoutMillis: syncConfig.queryTimeoutMillis,
+    },
+    allEventParams,
+    ~checksumAddresses,
+  )
   {
     getHeight: () => client.getHeight()->Promise.catch(coerceErrorOrThrow),
+    getNextPage: params => client.getNextPage(params)->Promise.catch(coerceErrorOrThrow),
   }
 }

package/src/sources/EvmRpcClient.res.mjs

@@ -46,13 +46,22 @@ function coerceErrorOrThrow(exn) {
   throw exn;
 }
 
-function make(url, httpReqTimeoutMillis) {
+function make(url, checksumAddresses, syncConfig, httpReqTimeoutMillis, headers, allEventParamsOpt) {
+  let allEventParams = allEventParamsOpt !== undefined ? allEventParamsOpt : [];
   let client = Core.getAddon().EvmRpcClient.new({
     url: url,
-    httpReqTimeoutMillis: httpReqTimeoutMillis
-  });
+    httpReqTimeoutMillis: httpReqTimeoutMillis,
+    headers: headers,
+    initialBlockInterval: syncConfig.initialBlockInterval,
+    backoffMultiplicative: syncConfig.backoffMultiplicative,
+    accelerationAdditive: syncConfig.accelerationAdditive,
+    intervalCeiling: syncConfig.intervalCeiling,
+    backoffMillis: syncConfig.backoffMillis,
+    queryTimeoutMillis: syncConfig.queryTimeoutMillis
+  }, allEventParams, checksumAddresses);
   return {
-    getHeight: () => Stdlib_Promise.$$catch(client.getHeight(), coerceErrorOrThrow)
+    getHeight: () => Stdlib_Promise.$$catch(client.getHeight(), coerceErrorOrThrow),
+    getNextPage: params => Stdlib_Promise.$$catch(client.getNextPage(params), coerceErrorOrThrow)
   };
 }
 

package/src/sources/FieldMask.res

@@ -0,0 +1,39 @@
+// Selection-bitmask helpers shared by the per-chain field stores
+// (`TransactionStore`, `BlockStore`). A field's bit index is its position in the
+// ecosystem's ordered field-name array — the same code the Rust store uses.
+
+// Field-name → bit-index map from an ordered field-name array.
+let fieldCodes = (fields: array<string>): dict<int> => {
+  let codes = Dict.make()
+  fields->Array.forEachWithIndex((name, i) => codes->Dict.set(name, i))
+  codes
+}
+
+let pow2: int => float = %raw(`c => Math.pow(2, c)`)
+
+// One event's selected fields as a bitmask float (bit `code` set ⇔ selected).
+// Each field appears once, so summing `pow2(code)` sets distinct bits with no
+// overlap; the result stays exact in f64 (codes span 0..31, so a mask is at most
+// 2^32-1).
+let maskFromFields = (selectedFields: Utils.Set.t<string>, ~codes: dict<int>): float => {
+  let mask = ref(0.)
+  selectedFields->Utils.Set.forEach(name =>
+    switch codes->Utils.Dict.dangerouslyGetNonOption(name) {
+    | Some(code) => mask := mask.contents +. pow2(code)
+    | None => ()
+    }
+  )
+  mask.contents
+}
+
+// Build an ecosystem's per-event mask function from its ordered field-name
+// array. The field codes are derived once and closed over.
+let makeMaskFn = (fields: array<string>): (Utils.Set.t<string> => float) => {
+  let codes = fieldCodes(fields)
+  selectedFields => selectedFields->maskFromFields(~codes)
+}
+
+// Bitwise OR of two per-event masks. Masks fit in 32 bits (≤32 fields), so
+// `>>> 0` recovers the unsigned value that a plain `|` renders negative once bit
+// 31 is set.
+let orMask: (float, float) => float = %raw(`(a, b) => (a | b) >>> 0`)