envio 3.3.0-alpha.1 → 3.3.0-alpha.2

package/src/sources/SvmHyperSyncSource.res

@@ -188,7 +188,6 @@ let toSvmInstruction = (
   instr: SvmHyperSyncClient.ResponseTypes.instruction,
   ~programName,
   ~instructionName,
-  ~transaction,
   ~logs,
   ~block,
 ): Envio.svmInstruction => {
@@ -204,35 +203,10 @@ let toSvmInstruction = (
   d4: ?instr.d4,
   d8: ?instr.d8,
   params: ?(instr.decoded->Option.map(parseDecoded)),
-  ?transaction,
   ?logs,
   block,
 }
 
-let toSvmTransaction = (tx: SvmHyperSyncClient.ResponseTypes.transaction): Envio.svmTransaction => {
-  signatures: tx.signatures,
-  accountKeys: tx.accountKeys->SvmTypes.Pubkey.fromStringsUnsafe,
-  feePayer: ?(tx.feePayer->Option.map(SvmTypes.Pubkey.fromStringUnsafe)),
-  success: ?tx.success,
-  err: ?tx.err,
-  // u64 lamports / compute units arrive as `int` over napi. Convert to
-  // `bigint` so the public type stays defensible even for pathological values.
-  fee: ?(tx.fee->Option.map(BigInt.fromInt)),
-  computeUnitsConsumed: ?(tx.computeUnitsConsumed->Option.map(BigInt.fromInt)),
-  recentBlockhash: ?tx.recentBlockhash,
-  version: ?tx.version,
-}
-
-let toSvmTokenBalance = (
-  tb: SvmHyperSyncClient.ResponseTypes.tokenBalance,
-): Envio.svmTokenBalance => {
-  account: ?(tb.account->Option.map(SvmTypes.Pubkey.fromStringUnsafe)),
-  mint: ?(tb.mint->Option.map(SvmTypes.Pubkey.fromStringUnsafe)),
-  owner: ?(tb.owner->Option.map(SvmTypes.Pubkey.fromStringUnsafe)),
-  preAmount: ?tb.preAmount,
-  postAmount: ?tb.postAmount,
-}
-
 // Probe the discriminator byte-length ordering longest-first. Stops at the
 // first router hit. Falls back to the `_none` key (program-wide handler) when
 // no discriminator-keyed handler matches.
@@ -273,6 +247,27 @@ let probeRouter = (
   }
 }
 
+// Map a selected transaction field to the extra query-side column it needs.
+// `transactionIndex` is always fetched as the store key, and `tokenBalances`
+// lives in a separate table (requested via `needsTokenBalances`), so neither
+// adds a transaction column here.
+let toQueryTxField = (field: Internal.svmTransactionField): option<
+  SvmHyperSyncClient.QueryTypes.transactionField,
+> =>
+  switch field {
+  | TransactionIndex => None
+  | Signatures => Some(Signatures)
+  | FeePayer => Some(FeePayer)
+  | Success => Some(Success)
+  | Err => Some(Err)
+  | Fee => Some(Fee)
+  | ComputeUnitsConsumed => Some(ComputeUnitsConsumed)
+  | AccountKeys => Some(AccountKeys)
+  | RecentBlockhash => Some(RecentBlockhash)
+  | Version => Some(Version)
+  | TokenBalances => None
+  }
+
 let make = ({chain, endpointUrl, apiToken, eventConfigs, clientTimeoutMillis}: options): t => {
   let name = "SvmHyperSync"
   let chainId = chain->ChainMap.Chain.toChainId
@@ -298,9 +293,38 @@ let make = ({chain, endpointUrl, apiToken, eventConfigs, clientTimeoutMillis}: o
     orderingByProgram->Dict.set(o.programId->SvmTypes.Pubkey.toString, o.byteLengthsDesc)
   )
 
-  let needsTransactions = eventConfigs->Array.some(cfg => cfg.includeTransaction)
   let needsLogs = eventConfigs->Array.some(cfg => cfg.includeLogs)
-  let needsTokenBalances = eventConfigs->Array.some(cfg => cfg.includeTokenBalances)
+
+  // Union of selected transaction fields across the chain's events. Drives both
+  // the query column selection (fetch only what's used) and the materialisation
+  // mask. `slot`/`transactionIndex` are always fetched as the store key.
+  let selectedTxFields = Utils.Set.make()
+  eventConfigs->Array.forEach(cfg =>
+    cfg.selectedTransactionFields
+    ->(Utils.magic: Utils.Set.t<string> => Utils.Set.t<Internal.svmTransactionField>)
+    ->Utils.Set.forEach(field => selectedTxFields->Utils.Set.add(field)->ignore)
+  )
+  let needsTokenBalances = selectedTxFields->Utils.Set.has(Internal.TokenBalances)
+  let txQueryFields = {
+    // Slot + TransactionIndex are always fetched so the store can be keyed by
+    // (slot, transactionIndex).
+    let fields: array<SvmHyperSyncClient.QueryTypes.transactionField> = [Slot, TransactionIndex]
+    selectedTxFields
+    ->Utils.Set.toArray
+    ->Array.forEach(field =>
+      switch toQueryTxField(field) {
+      | Some(queryField) => fields->Array.push(queryField)
+      | None => ()
+      }
+    )
+    fields
+  }
+  // Every selected field except `tokenBalances` (its own table) is read off a
+  // stored transaction record, so the transaction table must be fetched to
+  // populate the store — even when only `transactionIndex` (a key column) is
+  // selected.
+  let txFieldCount = selectedTxFields->Utils.Set.size
+  let needsTransactions = txFieldCount > 1 || (txFieldCount === 1 && !needsTokenBalances)
 
   let getItemsOrThrow = async (
     ~fromBlock,
@@ -323,23 +347,7 @@ let make = ({chain, endpointUrl, apiToken, eventConfigs, clientTimeoutMillis}: o
     // opted-into table needs its columns spelled out here.
     let fields: SvmHyperSyncClient.QueryTypes.fieldSelection = {
       block: [Slot, Blockhash, BlockTime],
-      transaction: ?(
-        needsTransactions
-          ? Some([
-              Slot,
-              TransactionIndex,
-              Signatures,
-              FeePayer,
-              Success,
-              Err,
-              Fee,
-              ComputeUnitsConsumed,
-              AccountKeys,
-              RecentBlockhash,
-              Version,
-            ])
-          : None
-      ),
+      transaction: ?(needsTransactions ? Some(txQueryFields) : None),
       log: ?(needsLogs ? Some([Slot, TransactionIndex, InstructionAddress, Kind, Message]) : None),
       tokenBalance: ?(
         needsTokenBalances
@@ -358,7 +366,7 @@ let make = ({chain, endpointUrl, apiToken, eventConfigs, clientTimeoutMillis}: o
 
     Prometheus.SourceRequestCount.increment(~sourceName=name, ~chainId, ~method="getInstructions")
 
-    let resp = try await client.get(~query) catch {
+    let (resp, transactionStore) = try await client.get(~query) catch {
     | exn =>
       throw(
         Source.GetItemsError(
@@ -390,13 +398,6 @@ let make = ({chain, endpointUrl, apiToken, eventConfigs, clientTimeoutMillis}: o
       }
     })
 
-    // Per (slot, transaction_index) lookup for parent transactions.
-    let txByKey = Dict.make()
-    resp.data.transactions->Array.forEach(tx => {
-      let key = tx.slot->Int.toString ++ ":" ++ tx.transactionIndex->Int.toString
-      txByKey->Dict.set(key, tx)
-    })
-
     // Per (slot, transaction_index, instruction_address) lookup for logs
     // scoped to a single instruction. `instructionAddress: None` logs are
     // attached to no instruction (rare; usually only system messages).
@@ -418,21 +419,6 @@ let make = ({chain, endpointUrl, apiToken, eventConfigs, clientTimeoutMillis}: o
       }
     })
 
-    let tokenBalancesByTx = Dict.make()
-    if needsTokenBalances {
-      resp.data.tokenBalances->Array.forEach(tb => {
-        switch tb.transactionIndex {
-        | Some(txIdx) =>
-          let key = tb.slot->Int.toString ++ ":" ++ txIdx->Int.toString
-          switch tokenBalancesByTx->Dict.get(key) {
-          | Some(existing) => existing->Array.push(tb)
-          | None => tokenBalancesByTx->Dict.set(key, [tb])
-          }
-        | None => ()
-        }
-      })
-    }
-
     let parsedQueueItems = []
     resp.data.instructions->Array.forEach(instr => {
       let programId = instr.programId->SvmTypes.Pubkey.fromStringUnsafe
@@ -454,20 +440,6 @@ let make = ({chain, endpointUrl, apiToken, eventConfigs, clientTimeoutMillis}: o
       switch maybeConfig {
       | None => ()
       | Some(eventConfig) =>
-        let txKey = instr.slot->Int.toString ++ ":" ++ instr.transactionIndex->Int.toString
-        let maybeTx =
-          txByKey->Utils.Dict.dangerouslyGetNonOption(txKey)->Option.map(toSvmTransaction)
-        let maybeTx = if eventConfig.includeTokenBalances {
-          maybeTx->Option.map(tx => {
-            let maybeBalances =
-              tokenBalancesByTx
-              ->Utils.Dict.dangerouslyGetNonOption(txKey)
-              ->Option.map(bals => bals->Array.map(toSvmTokenBalance))
-            {...tx, tokenBalances: ?maybeBalances}
-          })
-        } else {
-          maybeTx
-        }
         let logKey =
           instr.slot->Int.toString ++
           ":" ++
@@ -492,7 +464,6 @@ let make = ({chain, endpointUrl, apiToken, eventConfigs, clientTimeoutMillis}: o
           instr,
           ~programName=eventConfig.contractName,
           ~instructionName=eventConfig.name,
-          ~transaction=eventConfig.includeTransaction ? maybeTx : None,
           ~logs=eventConfig.includeLogs ? maybeLogs : None,
           ~block={
             slot: instr.slot,
@@ -510,6 +481,8 @@ let make = ({chain, endpointUrl, apiToken, eventConfigs, clientTimeoutMillis}: o
             blockNumber: instr.slot,
             blockHash: "",
             logIndex: synthLogIndex(instr),
+            // The parent transaction is materialised from the store at batch prep.
+            transactionIndex: instr.transactionIndex,
             payload: payload->(Utils.magic: Envio.svmInstruction => Internal.eventPayload),
           }),
         )
@@ -539,6 +512,8 @@ let make = ({chain, endpointUrl, apiToken, eventConfigs, clientTimeoutMillis}: o
     {
       latestFetchedBlockTimestamp: latestBlockTime,
       parsedQueueItems,
+      // Raw transactions kept in Rust; materialised (selected fields) at batch prep.
+      transactionStore: Some(transactionStore),
       latestFetchedBlockNumber: highestSlot,
       stats: {totalTimeElapsed, parsingTimeElapsed, pageFetchTime},
       knownHeight,
@@ -563,7 +538,8 @@ let make = ({chain, endpointUrl, apiToken, eventConfigs, clientTimeoutMillis}: o
         maxNumBlocks: 1000,
       }
       Prometheus.SourceRequestCount.increment(~sourceName=name, ~chainId, ~method="getBlockHashes")
-      let resp = await client.get(~query)
+      // Block-only query; the store page is empty.
+      let (resp, _) = await client.get(~query)
       resp.data.blocks->Array.forEach(b =>
         blockDatas
         ->Array.push({

package/src/sources/SvmHyperSyncSource.res.mjs

@@ -166,7 +166,7 @@ function parseDecoded(d) {
   };
 }
 
-function toSvmInstruction(instr, programName, instructionName, transaction, logs, block) {
+function toSvmInstruction(instr, programName, instructionName, logs, block) {
   return {
     programName: programName,
     instructionName: instructionName,
@@ -180,36 +180,11 @@ function toSvmInstruction(instr, programName, instructionName, transaction, logs
     d4: instr.d4,
     d8: instr.d8,
     params: Stdlib_Option.map(instr.decoded, parseDecoded),
-    transaction: transaction,
     logs: logs,
     block: block
   };
 }
 
-function toSvmTransaction(tx) {
-  return {
-    signatures: tx.signatures,
-    feePayer: Stdlib_Option.map(tx.feePayer, prim => prim),
-    success: tx.success,
-    err: tx.err,
-    fee: Stdlib_Option.map(tx.fee, prim => BigInt(prim)),
-    computeUnitsConsumed: Stdlib_Option.map(tx.computeUnitsConsumed, prim => BigInt(prim)),
-    accountKeys: tx.accountKeys,
-    recentBlockhash: tx.recentBlockhash,
-    version: tx.version
-  };
-}
-
-function toSvmTokenBalance(tb) {
-  return {
-    account: Stdlib_Option.map(tb.account, prim => prim),
-    mint: Stdlib_Option.map(tb.mint, prim => prim),
-    owner: Stdlib_Option.map(tb.owner, prim => prim),
-    preAmount: tb.preAmount,
-    postAmount: tb.postAmount
-  };
-}
-
 function probeRouter(router, programId, instr, byteLengthsDesc, contractAddress, indexingAddresses) {
   let probe = dN => {
     let tag = EventRouter.getSvmEventId(programId, dN);
@@ -247,6 +222,32 @@ function probeRouter(router, programId, instr, byteLengthsDesc, contractAddress,
   }
 }
 
+function toQueryTxField(field) {
+  switch (field) {
+    case "signatures" :
+      return "signatures";
+    case "feePayer" :
+      return "fee_payer";
+    case "success" :
+      return "success";
+    case "err" :
+      return "err";
+    case "fee" :
+      return "fee";
+    case "computeUnitsConsumed" :
+      return "compute_units_consumed";
+    case "accountKeys" :
+      return "account_keys";
+    case "recentBlockhash" :
+      return "recent_blockhash";
+    case "version" :
+      return "version";
+    case "transactionIndex" :
+    case "tokenBalances" :
+      return;
+  }
+}
+
 function make(param) {
   let eventConfigs = param.eventConfigs;
   let chain = param.chain;
@@ -259,9 +260,27 @@ function make(param) {
   match[1].forEach(o => {
     orderingByProgram[o.programId] = o.byteLengthsDesc;
   });
-  let needsTransactions = eventConfigs.some(cfg => cfg.includeTransaction);
   let needsLogs = eventConfigs.some(cfg => cfg.includeLogs);
-  let needsTokenBalances = eventConfigs.some(cfg => cfg.includeTokenBalances);
+  let selectedTxFields = new Set();
+  eventConfigs.forEach(cfg => {
+    cfg.selectedTransactionFields.forEach(field => {
+      selectedTxFields.add(field);
+    });
+  });
+  let needsTokenBalances = selectedTxFields.has("tokenBalances");
+  let fields = [
+    "slot",
+    "transaction_index"
+  ];
+  Array.from(selectedTxFields).forEach(field => {
+    let queryField = toQueryTxField(field);
+    if (queryField !== undefined) {
+      fields.push(queryField);
+      return;
+    }
+  });
+  let txFieldCount = selectedTxFields.size;
+  let needsTransactions = txFieldCount > 1 || txFieldCount === 1 && !needsTokenBalances;
   let getItemsOrThrow = async (fromBlock, toBlock, param, indexingAddresses, knownHeight, param$1, param$2, retry, logger) => {
     let totalTimeRef = Hrtime.makeTimer();
     let pageFetchRef = Hrtime.makeTimer();
@@ -271,19 +290,7 @@ function make(param) {
       "blockhash",
       "block_time"
     ];
-    let fields_transaction = needsTransactions ? [
-        "slot",
-        "transaction_index",
-        "signatures",
-        "fee_payer",
-        "success",
-        "err",
-        "fee",
-        "compute_units_consumed",
-        "account_keys",
-        "recent_blockhash",
-        "version"
-      ] : undefined;
+    let fields_transaction = needsTransactions ? fields : undefined;
     let fields_log = needsLogs ? [
         "slot",
         "transaction_index",
@@ -300,7 +307,7 @@ function make(param) {
         "pre_amount",
         "post_amount"
       ] : undefined;
-    let fields = {
+    let fields$1 = {
       block: fields_block,
       transaction: fields_transaction,
       log: fields_log,
@@ -308,7 +315,7 @@ function make(param) {
     };
     let query_toSlot = Stdlib_Option.map(toBlock, toBlock => toBlock + 1 | 0);
     let query_instructions = instructionSelections;
-    let query_fields = fields;
+    let query_fields = fields$1;
     let query = {
       fromSlot: fromBlock,
       toSlot: query_toSlot,
@@ -316,9 +323,9 @@ function make(param) {
       fields: query_fields
     };
     Prometheus.SourceRequestCount.increment(name, chain, "getInstructions");
-    let resp;
+    let match;
     try {
-      resp = await client.get(query);
+      match = await client.get(query);
     } catch (raw_exn) {
       let exn = Primitive_exceptions.internalToException(raw_exn);
       throw {
@@ -336,6 +343,7 @@ function make(param) {
         Error: new Error()
       };
     }
+    let resp = match[0];
     let pageFetchTime = Hrtime.toSecondsFloat(Hrtime.timeSince(pageFetchRef));
     let parsingRef = Hrtime.makeTimer();
     let blockTimeBySlot = {};
@@ -346,11 +354,6 @@ function make(param) {
         return;
       }
     });
-    let txByKey = {};
-    resp.data.transactions.forEach(tx => {
-      let key = tx.slot.toString() + ":" + tx.transactionIndex.toString();
-      txByKey[key] = tx;
-    });
     let logsByKey = {};
     resp.data.logs.forEach(log => {
       let match = log.transactionIndex;
@@ -369,22 +372,6 @@ function make(param) {
         logsByKey[key] = [log];
       }
     });
-    let tokenBalancesByTx = {};
-    if (needsTokenBalances) {
-      resp.data.tokenBalances.forEach(tb => {
-        let txIdx = tb.transactionIndex;
-        if (txIdx === undefined) {
-          return;
-        }
-        let key = tb.slot.toString() + ":" + txIdx.toString();
-        let existing = tokenBalancesByTx[key];
-        if (existing !== undefined) {
-          existing.push(tb);
-        } else {
-          tokenBalancesByTx[key] = [tb];
-        }
-      });
-    }
     let parsedQueueItems = [];
     resp.data.instructions.forEach(instr => {
       let programId = instr.programId;
@@ -392,14 +379,6 @@ function make(param) {
       let contractAddress = instr.programId;
       let maybeConfig = probeRouter(eventRouter, programId, instr, byteLengths, contractAddress, indexingAddresses);
       if (maybeConfig !== undefined) {
-        let txKey = instr.slot.toString() + ":" + instr.transactionIndex.toString();
-        let maybeTx = Stdlib_Option.map(txByKey[txKey], toSvmTransaction);
-        let maybeTx$1 = maybeConfig.includeTokenBalances ? Stdlib_Option.map(maybeTx, tx => {
-            let maybeBalances = Stdlib_Option.map(tokenBalancesByTx[txKey], bals => bals.map(toSvmTokenBalance));
-            let newrecord = {...tx};
-            newrecord.tokenBalances = maybeBalances;
-            return newrecord;
-          }) : maybeTx;
         let logKey = instr.slot.toString() + ":" + instr.transactionIndex.toString() + ":" + serializeInstructionAddress(instr.instructionAddress);
         let maybeLogs = Stdlib_Option.map(logsByKey[logKey], logs => logs.map(log => ({
           kind: Stdlib_Option.getOr(log.kind, ""),
@@ -407,7 +386,7 @@ function make(param) {
         })));
         let slotKey = instr.slot.toString();
         let blockTime = blockTimeBySlot[slotKey];
-        let payload = toSvmInstruction(instr, maybeConfig.contractName, maybeConfig.name, maybeConfig.includeTransaction ? maybeTx$1 : undefined, maybeConfig.includeLogs ? maybeLogs : undefined, {
+        let payload = toSvmInstruction(instr, maybeConfig.contractName, maybeConfig.name, maybeConfig.includeLogs ? maybeLogs : undefined, {
           slot: instr.slot,
           time: Stdlib_Option.getOr(blockTime, 0),
           hash: ""
@@ -420,6 +399,7 @@ function make(param) {
           blockNumber: instr.slot,
           blockHash: "",
           logIndex: synthLogIndex(instr),
+          transactionIndex: instr.transactionIndex,
           payload: payload
         });
       }
@@ -436,6 +416,7 @@ function make(param) {
       knownHeight: knownHeight,
       blockHashes: blockHashes,
       parsedQueueItems: parsedQueueItems,
+      transactionStore: Primitive_option.some(match[1]),
       fromBlockQueried: fromBlock,
       latestFetchedBlockNumber: highestSlot,
       latestFetchedBlockTimestamp: latestBlockTime,
@@ -469,7 +450,8 @@ function make(param) {
         maxNumBlocks: query_maxNumBlocks
       };
       Prometheus.SourceRequestCount.increment(name, chain, "getBlockHashes");
-      let resp = await client.get(query);
+      let match = await client.get(query);
+      let resp = match[0];
       resp.data.blocks.forEach(b => {
         blockDatas.push({
           blockHash: b.blockhash,
@@ -549,9 +531,8 @@ export {
   buildProgramSchemas,
   parseDecoded,
   toSvmInstruction,
-  toSvmTransaction,
-  toSvmTokenBalance,
   probeRouter,
+  toQueryTxField,
   make,
 }
 /* Prometheus Not a pure module */

package/src/sources/TransactionStore.res

@@ -0,0 +1,111 @@
+// Binding to the Rust `TransactionStore` napi class. Transactions are kept in
+// Rust as raw structs (their large fields never enter JS until read) keyed by
+// (blockNumber, transactionIndex). One store lives per chain on `ChainState`;
+// each fetch response contributes a page that is merged in. At batch
+// preparation the selected fields are materialised in bulk, off the JS thread,
+// in columnar form and zipped into plain JS objects on the main thread.
+type t
+
+@send external classNew: Core.transactionStoreCtor => t = "new"
+let make = (): t => Core.getAddon().transactionStore->classNew
+
+// Field-name → bit-index map from an ordered field-name array. The index is the
+// field code shared with the Rust store (`EvmTxField`/`SvmTxField`).
+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)`)
+
+// Union of an ecosystem's selected transaction fields as a bitmask float (bit
+// `code` set ⇔ selected). Built arithmetically to dodge 32-bit JS bitwise ops.
+let mask = (eventConfigs: array<Internal.eventConfig>, ~codes: dict<int>): float => {
+  let selected = Utils.Set.make()
+  eventConfigs->Array.forEach(eventConfig =>
+    eventConfig.selectedTransactionFields->Utils.Set.forEach(name =>
+      switch codes->Utils.Dict.dangerouslyGetNonOption(name) {
+      | Some(code) => selected->Utils.Set.add(code)->ignore
+      | None => ()
+      }
+    )
+  )
+  selected->Utils.Set.toArray->Array.reduce(0., (mask, code) => mask +. pow2(code))
+}
+
+// Drain another store (a fetch-response page) into this one.
+@send external merge: (t, t) => unit = "merge"
+
+// Bulk-materialise the fields selected by `mask` (one bit per field code) for
+// the given transactions, off the JS thread. Result is aligned with the input.
+@send
+external materialize: (
+  t,
+  ~blockNumbers: array<int>,
+  ~transactionIndices: array<int>,
+  ~mask: float,
+) => promise<array<Internal.eventTransaction>> = "materialize"
+
+// Drop transactions for blocks at or below the given block (already processed).
+@send external prune: (t, int) => unit = "prune"
+
+// Drop transactions for blocks above the given block (rolled back).
+@send external rollback: (t, int) => unit = "rollback"
+
+// Materialise the mask-selected fields for the store-backed items and write the
+// resulting transaction onto each item's payload. Items that already carry an
+// inline transaction (RPC/simulate/Fuel) are skipped. Store-backed items always
+// get a transaction object — the selected fields, or `{}` when the chain
+// selected none — so `event.transaction` is never `undefined` (matching the
+// inline sources). Deduped per (blockNumber, transactionIndex).
+let materializeItems = async (store: t, ~items: array<Internal.item>, ~mask: float) => {
+  // Store-backed items arrive in (block, logIndex) order, and a transaction's
+  // logs are contiguous within a block, so events sharing a (blockNumber,
+  // transactionIndex) are adjacent. Group them by extending the current run
+  // rather than hashing a string key per item. A key recurring non-adjacently
+  // just splits into two groups (one redundant decode) — never incorrect.
+  let blockNumbers = []
+  let transactionIndices = []
+  let payloadGroups = []
+
+  items->Array.forEach(item =>
+    switch item {
+    | Internal.Event(_) =>
+      let eventItem = item->Internal.castUnsafeEventItem
+      switch eventItem.payload->Internal.getPayloadTransaction->Nullable.toOption {
+      | Some(_) => () // RPC/simulate/Fuel carry the transaction inline.
+      | None =>
+        let {blockNumber, transactionIndex} = eventItem
+        let last = payloadGroups->Array.length - 1
+        if (
+          last >= 0 &&
+          blockNumbers->Array.getUnsafe(last) == blockNumber &&
+          transactionIndices->Array.getUnsafe(last) == transactionIndex
+        ) {
+          payloadGroups->Array.getUnsafe(last)->Array.push(eventItem.payload)
+        } else {
+          blockNumbers->Array.push(blockNumber)
+          transactionIndices->Array.push(transactionIndex)
+          payloadGroups->Array.push([eventItem.payload])
+        }
+      }
+    | Internal.Block(_) => ()
+    }
+  )
+
+  if payloadGroups->Utils.Array.notEmpty {
+    // A zero mask selects no fields, so there's nothing to decode — each
+    // store-backed item still gets an empty transaction object, so
+    // `event.transaction` is never undefined (matching the inline sources).
+    let txs = if mask == 0. {
+      payloadGroups->Array.map((_): Internal.eventTransaction => %raw(`{}`))
+    } else {
+      await store->materialize(~blockNumbers, ~transactionIndices, ~mask)
+    }
+    payloadGroups->Array.forEachWithIndex((payloads, i) => {
+      let tx = txs->Array.getUnsafe(i)
+      payloads->Array.forEach(payload => payload->Internal.setPayloadTransaction(tx))
+    })
+  }
+}

package/src/sources/TransactionStore.res.mjs

@@ -0,0 +1,77 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Core from "../Core.res.mjs";
+import * as Utils from "../Utils.res.mjs";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+
+function make() {
+  return Core.getAddon().TransactionStore.new();
+}
+
+function fieldCodes(fields) {
+  let codes = {};
+  fields.forEach((name, i) => {
+    codes[name] = i;
+  });
+  return codes;
+}
+
+let pow2 = (c => Math.pow(2, c));
+
+function mask(eventConfigs, codes) {
+  let selected = new Set();
+  eventConfigs.forEach(eventConfig => {
+    eventConfig.selectedTransactionFields.forEach(name => {
+      let code = codes[name];
+      if (code !== undefined) {
+        selected.add(code);
+        return;
+      }
+    });
+  });
+  return Stdlib_Array.reduce(Array.from(selected), 0, (mask, code) => mask + pow2(code));
+}
+
+async function materializeItems(store, items, mask) {
+  let blockNumbers = [];
+  let transactionIndices = [];
+  let payloadGroups = [];
+  items.forEach(item => {
+    if (item.kind !== 0) {
+      return;
+    }
+    let match = item.payload.transaction;
+    if (!(match == null)) {
+      return;
+    }
+    let transactionIndex = item.transactionIndex;
+    let blockNumber = item.blockNumber;
+    let last = payloadGroups.length - 1 | 0;
+    if (last >= 0 && blockNumbers[last] === blockNumber && transactionIndices[last] === transactionIndex) {
+      payloadGroups[last].push(item.payload);
+    } else {
+      blockNumbers.push(blockNumber);
+      transactionIndices.push(transactionIndex);
+      payloadGroups.push([item.payload]);
+    }
+  });
+  if (!Utils.$$Array.notEmpty(payloadGroups)) {
+    return;
+  }
+  let txs = mask === 0 ? payloadGroups.map(param => ({})) : await store.materialize(blockNumbers, transactionIndices, mask);
+  payloadGroups.forEach((payloads, i) => {
+    let tx = txs[i];
+    payloads.forEach(payload => {
+      payload.transaction = tx;
+    });
+  });
+}
+
+export {
+  make,
+  fieldCodes,
+  pow2,
+  mask,
+  materializeItems,
+}
+/* Core Not a pure module */