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

package/src/CrossChainState.res

@@ -57,7 +57,7 @@ let totalReadyCount = (crossChainState: t) => {
   let total = ref(0)
   for i in 0 to crossChainState.chainIds->Array.length - 1 {
     let cs = crossChainState->getChainState(crossChainState.chainIds->Array.getUnsafe(i))
-    total := total.contents + cs->ChainState.fetchState->FetchState.bufferReadyCount
+    total := total.contents + cs->ChainState.bufferReadyCount
   }
   total.contents
 }
@@ -65,9 +65,7 @@ let totalReadyCount = (crossChainState: t) => {
 // --- Derived (pure). ---
 
 let nextItemIsNone = (crossChainState: t): bool =>
-  !Batch.hasReadyItem(
-    crossChainState.chainStates->Dict.valuesToArray->Array.map(ChainState.fetchState),
-  )
+  !(crossChainState.chainStates->Dict.valuesToArray->Array.some(ChainState.hasReadyItem))
 
 let getSafeCheckpointId = (crossChainState: t) => {
   let result: ref<option<bigint>> = ref(None)
@@ -79,7 +77,7 @@ let getSafeCheckpointId = (crossChainState: t) => {
     | Some(safeCheckpointTracking) =>
       let safeCheckpointId =
         safeCheckpointTracking->SafeCheckpointTracking.getSafeCheckpointId(
-          ~sourceBlockNumber=(cs->ChainState.fetchState).knownHeight,
+          ~sourceBlockNumber=cs->ChainState.knownHeight,
         )
       switch result.contents {
       | None => result := Some(safeCheckpointId)
@@ -111,16 +109,9 @@ let createBatch = (
       // in an append-only ClickHouse insert.
       isRollback ? 1n : 0n,
     ),
-    ~chainsBeforeBatch=crossChainState.chainStates->Utils.Dict.mapValues((
-      cs
-    ): Batch.chainBeforeBatch => {
-      fetchState: cs->ChainState.fetchState,
-      progressBlockNumber: cs->ChainState.committedProgressBlockNumber,
-      totalEventsProcessed: cs->ChainState.numEventsProcessed,
-      sourceBlockNumber: (cs->ChainState.fetchState).knownHeight,
-      reorgDetection: cs->ChainState.reorgDetection,
-      chainConfig: cs->ChainState.chainConfig,
-    }),
+    ~chainsBeforeBatch=crossChainState.chainStates->Utils.Dict.mapValues(
+      ChainState.toChainBeforeBatch,
+    ),
     ~batchSizeTarget,
   )
 }
@@ -144,13 +135,13 @@ let enterReorgThreshold = (crossChainState: t) => {
 // whole indexer. A chain is marked caught up only once EVERY chain is caught up
 // (reached endblock or fetched/processed to head) with no processable events
 // left — so no chain flips to ready while another is still backfilling.
-let applyBatchProgress = (crossChainState: t, ~batch: Batch.t) => {
+let applyBatchProgress = (crossChainState: t, ~batch: Batch.t, ~blockTimestampName: string) => {
   let chainIds = crossChainState.chainIds
 
   let everyChainCaughtUp = ref(true)
   for i in 0 to chainIds->Array.length - 1 {
     let cs = crossChainState->getChainState(chainIds->Array.getUnsafe(i))
-    cs->ChainState.applyBatchProgress(~batch)
+    cs->ChainState.applyBatchProgress(~batch, ~blockTimestampName)
     if !(cs->ChainState.hasProcessedToEndblock || cs->ChainState.isProgressAtHead) {
       everyChainCaughtUp := false
     }
@@ -184,10 +175,7 @@ let priorityOrder = (crossChainState: t) =>
   crossChainState.chainStates
   ->Dict.valuesToArray
   ->Array.toSorted((a, b) =>
-    Float.compare(
-      a->ChainState.fetchState->FetchState.getProgressPercentage,
-      b->ChainState.fetchState->FetchState.getProgressPercentage,
-    )
+    Float.compare(a->ChainState.getProgressPercentage, b->ChainState.getProgressPercentage)
   )
 
 // In-flight estimated items across every chain — the live draw against
@@ -202,86 +190,122 @@ let totalReservedSize = (crossChainState: t) => {
   total.contents
 }
 
-// Furthest-behind first: order candidate queries by the chain progress % at
-// their fromBlock, so the most behind ranges across all chains are admitted
-// before the rest.
-let compareByProgress = (a: FetchState.query, b: FetchState.query) =>
-  Float.compare(a.progress, b.progress)
-
 // Dispatch a fetch tick across the whole indexer from one shared pool of
-// ~targetBufferSize ready events. Every chain proposes its candidate queries
-// (each carrying an estimated response size) against the full free budget; the
-// candidates are then pooled, ordered by chain progress (furthest-behind first),
-// and admitted until the budget is consumed. So the budget is split per query
-// across chains rather than per chain — a chain that can only use a little
-// leaves the rest for the others automatically.
+// ~targetBufferSize ready events, as a waterfall: visit chains furthest-behind
+// first, hand each the budget remaining at that point (plus its own
+// already-reserved share, since a chain's pending queries aren't "spent" —
+// they're this chain's), let it turn that into queries sized against its own
+// chain-density-derived target block, then subtract what it actually used
+// before moving to the next chain. So a chain that can only use a little
+// (density too low, or already caught up) leaves the rest for the others
+// automatically. A chain visited after the budget ran out simply doesn't
+// query this round — the leader's reservations release as its responses land,
+// so the next tick redistributes. Chains that do get budget are additionally
+// capped at the most-behind chain's target progress mapped onto their own
+// range, so no chain runs further ahead than the chain the pool is
+// prioritizing.
 let checkAndFetch = async (
   crossChainState: t,
   ~dispatchChain: (~chain: ChainMap.Chain.t, ~action: FetchState.nextQuery) => promise<unit>,
 ) => {
-  let remaining = Pervasives.max(
-    0,
-    crossChainState.targetBufferSize -
-    crossChainState->totalReadyCount -
-    crossChainState->totalReservedSize->Float.toInt,
+  let remaining = ref(
+    Pervasives.max(
+      0.,
+      crossChainState.targetBufferSize->Int.toFloat -.
+      crossChainState->totalReadyCount->Int.toFloat -.
+      crossChainState->totalReservedSize,
+    ),
   )
 
-  let chainIds = crossChainState.chainIds
+  // A chain with no density signal probes blind, so it only gets a bounded
+  // slice of the pool — one unknown chain shouldn't hold the whole budget
+  // while it takes its first measurements.
+  let coldChainBudget = Pervasives.min(5_000., crossChainState.targetBufferSize->Int.toFloat)
+
+  // Chunk reservations get headroom over the density estimate so a
+  // denser-than-expected range doesn't truncate at the server cap; realtime
+  // gets more since a forced catch-up query there costs a head-poll roundtrip.
+  let chunkItemsMultiplier = crossChainState.isRealtime ? 3. : 1.5
+
   let actionByChain = Dict.make()
-  // Candidate queries from every chain. Each query carries its chain id and the
-  // chain progress % at its fromBlock (the admission sort key), set here so the
-  // pool can be ordered without a side tuple per query.
-  let candidates = []
-  for i in 0 to chainIds->Array.length - 1 {
-    let chainId = chainIds->Array.getUnsafe(i)
-    let cs = crossChainState->getChainState(chainId)
-    let fetchState = cs->ChainState.fetchState
-    switch fetchState->FetchState.getNextQuery(
-      ~budget=remaining,
-      ~chainPendingBudget=cs->ChainState.pendingBudget,
-    ) {
-    | (WaitingForNewBlock | NothingToQuery) as action =>
-      actionByChain->Utils.Dict.setByInt(chainId, action)
-    | Ready(queries) =>
-      // Default to NothingToQuery; replaced below if any candidate is admitted.
-      actionByChain->Utils.Dict.setByInt(chainId, FetchState.NothingToQuery)
-      queries->Array.forEach(query => {
-        query.chainId = chainId
-        query.progress =
-          fetchState->FetchState.getProgressPercentageAt(~blockNumber=query.fromBlock)
-        candidates->Array.push(query)
-      })
+  let maxProgress = ref(None)
+  crossChainState
+  ->priorityOrder
+  ->Array.forEach(cs => {
+    let chainId = (cs->ChainState.chainConfig).id
+    if cs->ChainState.knownHeight == 0 {
+      // No height yet — nothing to size a budget or an alignment line
+      // against. Skip without consuming budget or claiming leadership, so a
+      // chain whose source hasn't reported doesn't unconstrain everyone else.
+      actionByChain->Utils.Dict.setByInt(chainId, FetchState.WaitingForNewBlock)
+    } else {
+      let isCold = cs->ChainState.effectiveDensity === None
+      let chainTargetItems =
+        (isCold ? Pervasives.min(remaining.contents, coldChainBudget) : remaining.contents) +.
+        cs->ChainState.pendingBudget
+      let maxTargetBlock = switch maxProgress.contents {
+      | None if isCold =>
+        // A cold chain's target is a guess — it doesn't set the alignment
+        // line; the first density-bearing chain after it does.
+        None
+      | None =>
+        // The most-behind chain sets the alignment line for everyone after it.
+        maxProgress :=
+          Some(
+            cs->ChainState.progressAtBlock(
+              ~blockNumber=cs->ChainState.targetBlock(~chainTargetItems),
+            ),
+          )
+        None
+      // 5% margin past the leader's line: chains whose progress tracks the
+      // leader closely would otherwise flap in and out of the clamp as
+      // leadership alternates, stalling their pipeline every other tick.
+      | Some(progress) => Some(cs->ChainState.blockAtProgress(~progress=progress +. 0.05))
+      }
+      switch cs->ChainState.getNextQuery(
+        ~chainTargetItems,
+        ~chunkItemsMultiplier,
+        ~maxTargetBlock?,
+      ) {
+      | (WaitingForNewBlock | NothingToQuery) as action =>
+        actionByChain->Utils.Dict.setByInt(chainId, action)
+      | Ready(queries) => {
+          let consumed =
+            queries->Array.reduce(0., (acc, query: FetchState.query) =>
+              acc +. query.itemsEst->Int.toFloat
+            )
+
+          let partitions = Dict.make()
+          queries->Array.forEach((query: FetchState.query) =>
+            partitions->Dict.set(
+              query.partitionId,
+              {
+                "fromBlock": query.fromBlock,
+                "targetBlock": query.toBlock,
+                "targetEvents": query.itemsTarget,
+              },
+            )
+          )
+          Logging.trace({
+            "msg": "Started querying",
+            "chainId": chainId,
+            "partitions": partitions,
+          })
+
+          actionByChain->Utils.Dict.setByInt(chainId, FetchState.Ready(queries))
+          // Mark the queries in flight and reserve their size against the
+          // shared budget; released as each response lands in
+          // handleQueryResult.
+          cs->ChainState.startFetchingQueries(~queries)
+          remaining := Pervasives.max(0., remaining.contents -. consumed)
+        }
+      }
     }
-  }
-
-  candidates->Array.sort(compareByProgress)
-
-  // Admit furthest-behind first until the budget runs out. The condition is
-  // checked before each query, so as long as there's any budget left we admit
-  // the next one even when its estimate alone exceeds the remainder — otherwise a
-  // chain whose only query is bigger than the budget would never make progress.
-  let admittedByChain = Dict.make()
-  let running = ref(0.)
-  let remainingF = remaining->Int.toFloat
-  let idx = ref(0)
-  while running.contents < remainingF && idx.contents < candidates->Array.length {
-    let query = candidates->Array.getUnsafe(idx.contents)
-    admittedByChain->Utils.Dict.push(query.chainId->Int.toString, query)
-    running := running.contents +. query.estResponseSize
-    idx := idx.contents + 1
-  }
-  admittedByChain->Dict.forEachWithKey((queries, chainId) => {
-    actionByChain->Dict.set(chainId, FetchState.Ready(queries))
-    // Mark the admitted queries in flight and reserve their size against the
-    // shared budget; released as each response lands in handleQueryResult.
-    crossChainState
-    ->getChainState(chainId->Int.fromString->Option.getUnsafe)
-    ->ChainState.startFetchingQueries(~queries)
   })
 
   let promises = []
-  for i in 0 to chainIds->Array.length - 1 {
-    let chainId = chainIds->Array.getUnsafe(i)
+  for i in 0 to crossChainState.chainIds->Array.length - 1 {
+    let chainId = crossChainState.chainIds->Array.getUnsafe(i)
     switch actionByChain->Utils.Dict.dangerouslyGetByIntNonOption(chainId) {
     | Some(NothingToQuery)
     | None => ()

package/src/CrossChainState.res.mjs

@@ -6,11 +6,8 @@ import * as Utils from "./Utils.res.mjs";
 import * as Logging from "./Logging.res.mjs";
 import * as ChainMap from "./ChainMap.res.mjs";
 import * as ChainState from "./ChainState.res.mjs";
-import * as FetchState from "./FetchState.res.mjs";
 import * as Prometheus from "./Prometheus.res.mjs";
-import * as Stdlib_Int from "@rescript/runtime/lib/es6/Stdlib_Int.js";
-import * as Stdlib_Dict from "@rescript/runtime/lib/es6/Stdlib_Dict.js";
-import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Primitive_float from "@rescript/runtime/lib/es6/Primitive_float.js";
 import * as SafeCheckpointTracking from "./SafeCheckpointTracking.res.mjs";
 
@@ -53,13 +50,13 @@ function totalReadyCount(crossChainState) {
   let total = 0;
   for (let i = 0, i_finish = crossChainState.chainIds.length; i < i_finish; ++i) {
     let cs = crossChainState.chainStates[crossChainState.chainIds[i]];
-    total = total + FetchState.bufferReadyCount(ChainState.fetchState(cs)) | 0;
+    total = total + ChainState.bufferReadyCount(cs) | 0;
   }
   return total;
 }
 
 function nextItemIsNone(crossChainState) {
-  return !Batch.hasReadyItem(Object.values(crossChainState.chainStates).map(ChainState.fetchState));
+  return !Object.values(crossChainState.chainStates).some(ChainState.hasReadyItem);
 }
 
 function getSafeCheckpointId(crossChainState) {
@@ -68,7 +65,7 @@ function getSafeCheckpointId(crossChainState) {
     let cs = crossChainState.chainStates[crossChainState.chainIds[i]];
     let safeCheckpointTracking = ChainState.safeCheckpointTracking(cs);
     if (safeCheckpointTracking !== undefined) {
-      let safeCheckpointId = SafeCheckpointTracking.getSafeCheckpointId(safeCheckpointTracking, ChainState.fetchState(cs).knownHeight);
+      let safeCheckpointId = SafeCheckpointTracking.getSafeCheckpointId(safeCheckpointTracking, ChainState.knownHeight(cs));
       let current = result;
       if (!(current !== undefined && safeCheckpointId >= current)) {
         result = safeCheckpointId;
@@ -84,14 +81,7 @@ function getSafeCheckpointId(crossChainState) {
 function createBatch(crossChainState, processedCheckpointId, batchSizeTarget, isRollback) {
   return Batch.make(processedCheckpointId + (
     isRollback ? 1n : 0n
-  ), Utils.Dict.mapValues(crossChainState.chainStates, cs => ({
-    fetchState: ChainState.fetchState(cs),
-    reorgDetection: ChainState.reorgDetection(cs),
-    progressBlockNumber: ChainState.committedProgressBlockNumber(cs),
-    sourceBlockNumber: ChainState.fetchState(cs).knownHeight,
-    totalEventsProcessed: ChainState.numEventsProcessed(cs),
-    chainConfig: ChainState.chainConfig(cs)
-  })), batchSizeTarget, crossChainState.isInReorgThreshold);
+  ), Utils.Dict.mapValues(crossChainState.chainStates, ChainState.toChainBeforeBatch), batchSizeTarget, crossChainState.isInReorgThreshold);
 }
 
 function enterReorgThreshold(crossChainState) {
@@ -103,12 +93,12 @@ function enterReorgThreshold(crossChainState) {
   crossChainState.isInReorgThreshold = true;
 }
 
-function applyBatchProgress(crossChainState, batch) {
+function applyBatchProgress(crossChainState, batch, blockTimestampName) {
   let chainIds = crossChainState.chainIds;
   let everyChainCaughtUp = true;
   for (let i = 0, i_finish = chainIds.length; i < i_finish; ++i) {
     let cs = crossChainState.chainStates[chainIds[i]];
-    ChainState.applyBatchProgress(cs, batch);
+    ChainState.applyBatchProgress(cs, batch, blockTimestampName);
     if (!(ChainState.hasProcessedToEndblock(cs) || ChainState.isProgressAtHead(cs))) {
       everyChainCaughtUp = false;
     }
@@ -131,7 +121,7 @@ function applyBatchProgress(crossChainState, batch) {
 }
 
 function priorityOrder(crossChainState) {
-  return Object.values(crossChainState.chainStates).toSorted((a, b) => Primitive_float.compare(FetchState.getProgressPercentage(ChainState.fetchState(a)), FetchState.getProgressPercentage(ChainState.fetchState(b))));
+  return Object.values(crossChainState.chainStates).toSorted((a, b) => Primitive_float.compare(ChainState.getProgressPercentage(a), ChainState.getProgressPercentage(b)));
 }
 
 function totalReservedSize(crossChainState) {
@@ -143,61 +133,75 @@ function totalReservedSize(crossChainState) {
   return total;
 }
 
-function compareByProgress(a, b) {
-  return Primitive_float.compare(a.progress, b.progress);
-}
-
 async function checkAndFetch(crossChainState, dispatchChain) {
-  let remaining = Primitive_int.max(0, (crossChainState.targetBufferSize - totalReadyCount(crossChainState) | 0) - (totalReservedSize(crossChainState) | 0) | 0);
-  let chainIds = crossChainState.chainIds;
+  let remaining = {
+    contents: Primitive_float.max(0, crossChainState.targetBufferSize - totalReadyCount(crossChainState) - totalReservedSize(crossChainState))
+  };
+  let coldChainBudget = Primitive_float.min(5000, crossChainState.targetBufferSize);
+  let chunkItemsMultiplier = crossChainState.isRealtime ? 3 : 1.5;
   let actionByChain = {};
-  let candidates = [];
-  for (let i = 0, i_finish = chainIds.length; i < i_finish; ++i) {
-    let chainId = chainIds[i];
-    let cs = crossChainState.chainStates[chainId];
-    let fetchState = ChainState.fetchState(cs);
-    let action = FetchState.getNextQuery(fetchState, remaining, ChainState.pendingBudget(cs));
+  let maxProgress = {
+    contents: undefined
+  };
+  priorityOrder(crossChainState).forEach(cs => {
+    let chainId = ChainState.chainConfig(cs).id;
+    if (ChainState.knownHeight(cs) === 0) {
+      actionByChain[chainId] = "WaitingForNewBlock";
+      return;
+    }
+    let isCold = ChainState.effectiveDensity(cs) === undefined;
+    let chainTargetItems = (
+      isCold ? Primitive_float.min(remaining.contents, coldChainBudget) : remaining.contents
+    ) + ChainState.pendingBudget(cs);
+    let progress = maxProgress.contents;
+    let maxTargetBlock = progress !== undefined ? ChainState.blockAtProgress(cs, progress + 0.05) : (
+        isCold ? undefined : (maxProgress.contents = ChainState.progressAtBlock(cs, ChainState.targetBlock(cs, chainTargetItems)), undefined)
+      );
+    let action = ChainState.getNextQuery(cs, chainTargetItems, chunkItemsMultiplier, maxTargetBlock);
     if (typeof action !== "object") {
+      if (action === "WaitingForNewBlock") {
+        actionByChain[chainId] = action;
+        return;
+      }
       actionByChain[chainId] = action;
+      return;
     } else {
-      actionByChain[chainId] = "NothingToQuery";
-      action._0.forEach(query => {
-        query.chainId = chainId;
-        query.progress = FetchState.getProgressPercentageAt(fetchState, query.fromBlock);
-        candidates.push(query);
+      let queries = action._0;
+      let consumed = Stdlib_Array.reduce(queries, 0, (acc, query) => acc + query.itemsEst);
+      let partitions = {};
+      queries.forEach(query => {
+        partitions[query.partitionId] = {
+          fromBlock: query.fromBlock,
+          targetBlock: query.toBlock,
+          targetEvents: query.itemsTarget
+        };
+      });
+      Logging.trace({
+        msg: "Started querying",
+        chainId: chainId,
+        partitions: partitions
       });
+      actionByChain[chainId] = {
+        TAG: "Ready",
+        _0: queries
+      };
+      ChainState.startFetchingQueries(cs, queries);
+      remaining.contents = Primitive_float.max(0, remaining.contents - consumed);
+      return;
     }
-  }
-  candidates.sort(compareByProgress);
-  let admittedByChain = {};
-  let running = 0;
-  let idx = 0;
-  while (running < remaining && idx < candidates.length) {
-    let query = candidates[idx];
-    Utils.Dict.push(admittedByChain, query.chainId.toString(), query);
-    running = running + query.estResponseSize;
-    idx = idx + 1 | 0;
-  };
-  Stdlib_Dict.forEachWithKey(admittedByChain, (queries, chainId) => {
-    actionByChain[chainId] = {
-      TAG: "Ready",
-      _0: queries
-    };
-    let chainId$1 = Stdlib_Int.fromString(chainId, undefined);
-    ChainState.startFetchingQueries(crossChainState.chainStates[chainId$1], queries);
   });
   let promises = [];
-  for (let i$1 = 0, i_finish$1 = chainIds.length; i$1 < i_finish$1; ++i$1) {
-    let chainId$1 = chainIds[i$1];
-    let action$1 = actionByChain[chainId$1];
-    if (action$1 !== undefined) {
+  for (let i = 0, i_finish = crossChainState.chainIds.length; i < i_finish; ++i) {
+    let chainId = crossChainState.chainIds[i];
+    let action = actionByChain[chainId];
+    if (action !== undefined) {
       let exit = 0;
-      if (typeof action$1 === "object" || action$1 === "WaitingForNewBlock") {
+      if (typeof action === "object" || action === "WaitingForNewBlock") {
         exit = 1;
       }
       if (exit === 1) {
-        let chain = ChainMap.Chain.makeUnsafe(chainId$1);
-        promises.push(dispatchChain(chain, action$1));
+        let chain = ChainMap.Chain.makeUnsafe(chainId);
+        promises.push(dispatchChain(chain, action));
       }
     }
   }

package/src/CrossChainState.resi

@@ -29,7 +29,7 @@ let createBatch: (
   ~isRollback: bool,
 ) => Batch.t
 let enterReorgThreshold: t => unit
-let applyBatchProgress: (t, ~batch: Batch.t) => unit
+let applyBatchProgress: (t, ~batch: Batch.t, ~blockTimestampName: string) => unit
 
 // Fetch control.
 let priorityOrder: t => array<ChainState.t>

package/src/Ecosystem.res

@@ -2,8 +2,6 @@ type name = | @as("evm") Evm | @as("fuel") Fuel | @as("svm") Svm
 
 type t = {
   name: name,
-  blockFields: array<string>,
-  transactionFields: array<string>,
   blockNumberName: string,
   blockTimestampName: string,
   blockHashName: string,
@@ -33,7 +31,8 @@ type t = {
       loggers (see `getItemLogger`). */
   logger: Pino.t,
   /** Materialise the user-facing event handed to handlers and contract
-      registration from an item's opaque payload. */
+      registration from an item's opaque payload. `event.transaction` is written
+      onto the payload at batch prep (HyperSync) or inline (RPC/simulate). */
   toEvent: Internal.eventItem => Internal.event,
   /** Build the per-item child logger for an event item, with
       ecosystem-specific log fields (EVM/Fuel: contract/event/address; SVM:
@@ -70,12 +69,12 @@ let getItemLogger = {
     | None =>
       let logger = switch item {
       | Internal.Event(_) => ecosystem.toEventLogger(item->Internal.castUnsafeEventItem)
-      | Block({blockNumber, onBlockConfig}) =>
+      | Block({blockNumber, onBlockRegistration}) =>
         Logging.createChildFrom(
           ~logger=ecosystem.logger,
           ~params={
-            "onBlock": onBlockConfig.name,
-            "chainId": onBlockConfig.chainId,
+            "onBlock": onBlockRegistration.name,
+            "chainId": onBlockRegistration.chainId,
             "block": blockNumber,
           },
         )

package/src/Ecosystem.res.mjs

@@ -26,10 +26,10 @@ function getItemLogger(item, ecosystem) {
   if (item.kind === 0) {
     logger$1 = ecosystem.toEventLogger(item);
   } else {
-    let onBlockConfig = item.onBlockConfig;
+    let onBlockRegistration = item.onBlockRegistration;
     logger$1 = Logging.createChildFrom(ecosystem.logger, {
-      onBlock: onBlockConfig.name,
-      chainId: onBlockConfig.chainId,
+      onBlock: onBlockRegistration.name,
+      chainId: onBlockRegistration.chainId,
       block: item.blockNumber
     });
   }

package/src/Envio.res

@@ -48,6 +48,7 @@ type svmTokenBalance = {
 }
 
 type svmTransaction = {
+  transactionIndex?: int,
   signatures: array<string>,
   feePayer?: SvmTypes.Pubkey.t,
   success?: bool,
@@ -65,18 +66,21 @@ type svmLog = {
   message: string,
 }
 
-/** Block context for a matched instruction. `time`/`hash` follow the
- EVM/Fuel field names so the shared `Ecosystem.t` getters in `Svm.res` read
- them uniformly. */
+/** Block context for a matched instruction. `slot`/`hash` are always present;
+ `time` can still be absent — HyperSync/Solana may not report a block time for
+ every slot. Every other field is opt-in via `field_selection.block_fields`,
+ materialised from the per-chain block store at batch prep. */
 type svmInstructionBlock = {
   /** Slot this instruction's block was matched in. */
   slot: int,
-  /** Unix block time (seconds). `0` when HyperSync didn't return a block
-   for this instruction's slot. */
-  time: int,
-  /** Block hash. Currently always empty — populated by the future
-   reorg-guard `queryBlockHash(slot)` route. */
+  /** Unix block time (seconds). */
+  time?: int,
   hash: string,
+  /** Block height (distinct from slot). Absent when not selected via
+   `field_selection.block_fields`. */
+  height?: int,
+  parentSlot?: int,
+  parentHash?: string,
 }
 
 /** The per-instruction payload handlers receive as their `instruction`
@@ -104,13 +108,15 @@ type svmInstruction = {
   d8?: string,
   /** Borsh-decoded params view. See [[svmInstructionParams]]. */
   params?: svmInstructionParams,
-  /** Parent transaction. Absent when the per-instruction
-   `include_transaction` flag is `false`. */
+  /** Parent transaction. Carries only the fields selected via
+   `field_selection.transaction_fields`; absent when none are selected. */
   transaction?: svmTransaction,
   /** Program log entries scoped to this instruction. Absent when the
    per-instruction `include_logs` flag is `false`. */
   logs?: array<svmLog>,
-  block: svmInstructionBlock,
+  // Omitted on construction; materialised onto the payload at batch prep,
+  // before a handler ever reads it.
+  block?: svmInstructionBlock,
 }
 
 /** Arguments passed to handlers registered via `indexer.onInstruction`. */

package/src/EnvioGlobal.res

@@ -0,0 +1,53 @@
+// The single process-wide mutable state record, stashed on `globalThis` so a
+// duplicate envio module instance — e.g. when the CLI's `bin.mjs` resolves
+// envio from one path but the user's handlers resolve it from
+// `node_modules/envio` — shares one state. Without this, each copy keeps its
+// own module-level state: registration would read an empty registry and the
+// `indexer.chains` getters would silently fall back to static config values.
+//
+// Slots are opaque (`unknown`) so this module stays at the bottom of the
+// dependency graph; each owning module casts its slot to the real type once
+// (`HandlerRegister` for the registration slots, `Main` for the runtime
+// slots, `RollbackCommit` for its callbacks).
+//
+// Version-gated: the slot shapes can evolve between envio versions, so the
+// guard uses strict full-version equality. On mismatch we throw with a
+// deduplication hint instead of silently mixing shapes across builds.
+type t = {
+  version: string,
+  eventRegistrations: dict<unknown>,
+  mutable activeRegistration: option<unknown>,
+  preRegistered: array<unknown>,
+  rollbackCommitCallbacks: array<unknown>,
+  mutable indexerState: option<unknown>,
+  mutable persistence: option<unknown>,
+}
+
+// Record type with `mutable` so assignment typechecks; ReScript keeps the
+// field name verbatim in the generated JS so the globalThis slot is
+// `__envioGlobal`.
+type globalThis = {mutable __envioGlobal: Nullable.t<t>}
+@val external globalThis: globalThis = "globalThis"
+
+let value: t = {
+  let version = Utils.EnvioPackage.value.version
+  switch globalThis.__envioGlobal->Nullable.toOption {
+  | Some(existing) if existing.version === version => existing
+  | Some(existing) =>
+    JsError.throwWithMessage(
+      `Multiple incompatible envio versions loaded in the same process: ${existing.version} and ${version}. Deduplicate the 'envio' dependency in your project.`,
+    )
+  | None =>
+    let fresh = {
+      version,
+      eventRegistrations: Dict.make(),
+      activeRegistration: None,
+      preRegistered: [],
+      rollbackCommitCallbacks: [],
+      indexerState: None,
+      persistence: None,
+    }
+    globalThis.__envioGlobal = Nullable.make(fresh)
+    fresh
+  }
+}