envio 3.11.0 → 3.12.1

package/src/Config.res

@@ -136,9 +136,17 @@ type t = {
   reorgThresholdReadyTolerance: int,
   lowercaseAddresses: bool,
   isDev: bool,
+  // An `envio start --chain` process: drives a subset of the schema's chains
+  // while sibling processes drive the rest, so it only touches what its own
+  // chains own — their partitions' indexes, their `ready_at`, their resume.
+  isolated: bool,
   userEntitiesByName: dict<Internal.entityConfig>,
   userEntities: array<Internal.entityConfig>,
   allEnums: array<Table.enumConfig<Table.enum>>,
+  // Whether checkpoint ids come from one counter or one per chain. Decided by
+  // the schema alone: a cross-chain entity has rows any chain's reorg can
+  // reach, so its checkpoints have to be comparable across chains.
+  checkpointSequence: CheckpointSequence.t,
 }
 
 type rpcSourceFor = | @as("sync") Sync | @as("fallback") Fallback | @as("realtime") Realtime
@@ -586,6 +594,7 @@ let publicConfigSchema = S.schema(s =>
     "description": s.matches(S.option(S.string)),
     "handlers": s.matches(S.option(S.string)),
     "isDev": s.matches(S.option(S.bool)),
+    "isolatedChains": s.matches(S.option(S.array(ChainId.schema))),
     "fullBatchSize": s.matches(S.option(S.int)),
     "rollbackOnReorg": s.matches(S.option(S.bool)),
     "saveFullHistory": s.matches(S.option(S.bool)),
@@ -609,6 +618,44 @@ let contractMappingOf = (~chainConfigs: array<chain>): ContractMapping.t => {
   ContractMapping.make(~names)
 }
 
+let getChain = (config, ~chainId) =>
+  config.chainMap->ChainMap.has(chainId)
+    ? chainId
+    : JsError.throwWithMessage(
+        "No chain with id " ++ chainId->ChainId.toString ++ " found in config.yaml",
+      )
+
+// Narrows a config to the chains one `envio start --chain` process drives.
+// `contractMapping` is deliberately left whole: its ids are what the migration
+// that created the schema stored, and one rebuilt from a subset would hand the
+// same contract a different id.
+let isolate = (config: t, ~chainIds: array<ChainId.t>) => {
+  // Chains indexed in separate processes each advance their own checkpoint
+  // counter, which only holds while no entity has rows another chain can reach.
+  switch config.userEntities->Array.filter(entityConfig => entityConfig.crossChain) {
+  | [] => ()
+  | shared =>
+    JsError.throwWithMessage(
+      `Only a schema whose entities are all per-chain can be split across processes. Shared across chains: ${shared
+        ->Array.map(entityConfig => entityConfig.name)
+        ->Array.joinUnsafe(", ")}.`,
+    )
+  }
+  chainIds->Array.forEach(chainId => config->getChain(~chainId)->ignore)
+
+  // Filtered out of the config's own chain order rather than built from the
+  // argument order, so a repeated `--chain` collapses and `defaultChain` doesn't
+  // depend on how the flags were typed.
+  let chains =
+    config.chainMap->ChainMap.values->Array.filter(chain => chainIds->Array.includes(chain.id))
+  {
+    ...config,
+    chainMap: chains->Array.map(chain => (chain.id, chain))->ChainMap.fromArrayUnsafe,
+    defaultChain: chains->Array.get(0),
+    isolated: true,
+  }
+}
+
 let fromPublic = (publicConfigJson: JSON.t) => {
   let maxAddrInPartition = Env.maxAddrInPartition
   // Parse public config
@@ -709,12 +756,7 @@ let fromPublic = (publicConfigJson: JSON.t) => {
       }
       let widened =
         contractConfig->(
-          Utils.magic: _ => {
-            "svmAbi": option<{
-              "definedTypes": JSON.t,
-              "source": string,
-            }>,
-          }
+          Utils.magic: _ => {"svmAbi": option<{"definedTypes": JSON.t, "source": string}>}
         )
       contractDataByName->Dict.set(
         capitalizedName,
@@ -1063,7 +1105,7 @@ let fromPublic = (publicConfigJson: JSON.t) => {
   | None => []
   }
 
-  {
+  let config = {
     name: publicConfig["name"],
     description: publicConfig["description"],
     handlers: publicConfig["handlers"]->Option.getOr("src/handlers"),
@@ -1084,19 +1126,18 @@ let fromPublic = (publicConfigJson: JSON.t) => {
     reorgThresholdReadyTolerance: 100,
     lowercaseAddresses,
     isDev: publicConfig["isDev"]->Option.getOr(false),
+    isolated: false,
     userEntitiesByName,
     userEntities,
     allEnums,
+    checkpointSequence: CheckpointSequence.fromEntities(userEntities),
   }
-}
 
-// With no cross-chain entity, a reorg on one chain can never have changed a row
-// another chain owns, so its rollback stays isolated to that chain instead of
-// dragging every sibling back with it. A single chain has no sibling to spare,
-// and narrowing its rollback would only buy it a predicate that always holds.
-let isIsolatedMultichain = (config: t) =>
-  config.chainMap->ChainMap.keys->Array.length > 1 &&
-    config.userEntities->Array.every(entityConfig => !entityConfig.crossChain)
+  switch publicConfig["isolatedChains"] {
+  | None => config
+  | Some(chainIds) => config->isolate(~chainIds)
+  }
+}
 
 // Canonicalize a user-provided address to the configured casing so it matches
 // addresses parsed from config.yaml during routing. HyperSync/RPC data arrives
@@ -1169,33 +1210,12 @@ let getEventConfig = (config: t, ~contractName, ~eventName, ~chainId: option<Cha
   })
 }
 
-// A chain that can't be rolled back (maxReorgDepth = 0) has no history to keep,
-// unless a cross-chain entity lets another chain's rollback reach its rows.
-let shouldSaveHistory = (config, ~isInReorgThreshold, ~chainId: option<ChainId.t>=?) =>
-  config.shouldSaveFullHistory ||
-  (config.shouldRollbackOnReorg &&
-  isInReorgThreshold &&
-  switch chainId {
-  | Some(chainId) if config->isIsolatedMultichain =>
-    (config.chainMap->ChainMap.get(chainId)).maxReorgDepth > 0
-  | _ => true
-  })
-
-let shouldPruneHistory = (config, ~isInReorgThreshold) =>
-  !config.shouldSaveFullHistory && (config.shouldRollbackOnReorg && isInReorgThreshold)
-
-let getChain = (config, ~chainId) =>
-  config.chainMap->ChainMap.has(chainId)
-    ? chainId
-    : JsError.throwWithMessage(
-        "No chain with id " ++ chainId->ChainId.toString ++ " found in config.yaml",
-      )
-
 // A CLI command payload already contains the resolved JSON; priming lets
 // downstream callers skip the NAPI `getConfigJson` round-trip. Calling
 // `prime` again invalidates the memo.
 %%private(let primedJson: ref<option<JSON.t>> = ref(None))
 %%private(let cached: ref<option<t>> = ref(None))
+
 let prime = (json: JSON.t): unit => {
   primedJson := Some(json)
   cached := None
@@ -1236,6 +1256,7 @@ let stripSensitiveData = (json: JSON.t): JSON.t => {
   switch cloned {
   | Object(obj) => {
       obj->Utils.Dict.deleteInPlace("isDev")
+      obj->Utils.Dict.deleteInPlace("isolatedChains")
       stripChains(obj->Dict.get("evm"))
       stripChains(obj->Dict.get("fuel"))
       stripChains(obj->Dict.get("svm"))

package/src/Config.res.mjs

@@ -21,6 +21,7 @@ import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
 import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
+import * as CheckpointSequence from "./db/CheckpointSequence.res.mjs";
 import * as EventConfigBuilder from "./EventConfigBuilder.res.mjs";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 
@@ -436,6 +437,7 @@ let publicConfigSchema = S$RescriptSchema.schema(s => ({
   description: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
   handlers: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
   isDev: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
+  isolatedChains: s.m(S$RescriptSchema.option(S$RescriptSchema.array(ChainId.schema))),
   fullBatchSize: s.m(S$RescriptSchema.option(S$RescriptSchema.int)),
   rollbackOnReorg: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   saveFullHistory: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
@@ -460,6 +462,33 @@ function contractMappingOf(chainConfigs) {
   return ContractMapping.make(names);
 }
 
+function getChain(config, chainId) {
+  if (ChainMap.has(config.chainMap, chainId)) {
+    return chainId;
+  } else {
+    return Stdlib_JsError.throwWithMessage("No chain with id " + ChainId.toString(chainId) + " found in config.yaml");
+  }
+}
+
+function isolate(config, chainIds) {
+  let shared = config.userEntities.filter(entityConfig => entityConfig.crossChain);
+  if (shared.length !== 0) {
+    Stdlib_JsError.throwWithMessage(`Only a schema whose entities are all per-chain can be split across processes. Shared across chains: ` + shared.map(entityConfig => entityConfig.name).join(", ") + `.`);
+  }
+  chainIds.forEach(chainId => {
+    getChain(config, chainId);
+  });
+  let chains = ChainMap.values(config.chainMap).filter(chain => chainIds.includes(chain.id));
+  let newrecord = {...config};
+  newrecord.isolated = true;
+  newrecord.defaultChain = chains[0];
+  newrecord.chainMap = ChainMap.fromArrayUnsafe(chains.map(chain => [
+    chain.id,
+    chain
+  ]));
+  return newrecord;
+}
+
 function fromPublic(publicConfigJson) {
   let publicConfig;
   try {
@@ -755,38 +784,50 @@ function fromPublic(publicConfigJson) {
       name: Utils.$$String.capitalize(param[0]),
       handler: param[1].handler
     })) : [];
-  return {
-    name: publicConfig.name,
-    description: publicConfig.description,
-    handlers: Stdlib_Option.getOr(publicConfig.handlers, "src/handlers"),
+  let config_name = publicConfig.name;
+  let config_description = publicConfig.description;
+  let config_handlers = Stdlib_Option.getOr(publicConfig.handlers, "src/handlers");
+  let config_shouldRollbackOnReorg = Stdlib_Option.getOr(publicConfig.rollbackOnReorg, true);
+  let config_shouldSaveFullHistory = Stdlib_Option.getOr(publicConfig.saveFullHistory, false);
+  let config_chainIdMode = Stdlib_Option.getOr(publicConfig.chainIdMode, "int32");
+  let config_contractMapping = contractMappingOf(chains);
+  let config_defaultChain = chains[0];
+  let config_enableRawEvents = Stdlib_Option.getOr(publicConfig.rawEvents, false);
+  let config_batchSize = Stdlib_Option.getOr(publicConfig.fullBatchSize, 5000);
+  let config_isDev = Stdlib_Option.getOr(publicConfig.isDev, false);
+  let config_checkpointSequence = CheckpointSequence.fromEntities(userEntities);
+  let config = {
+    name: config_name,
+    description: config_description,
+    handlers: config_handlers,
     contractHandlers: contractHandlers,
-    shouldRollbackOnReorg: Stdlib_Option.getOr(publicConfig.rollbackOnReorg, true),
-    shouldSaveFullHistory: Stdlib_Option.getOr(publicConfig.saveFullHistory, false),
+    shouldRollbackOnReorg: config_shouldRollbackOnReorg,
+    shouldSaveFullHistory: config_shouldSaveFullHistory,
     defaultCrossChain: defaultCrossChain,
     storage: globalStorage,
-    chainIdMode: Stdlib_Option.getOr(publicConfig.chainIdMode, "int32"),
+    chainIdMode: config_chainIdMode,
     chainMap: chainMap,
-    contractMapping: contractMappingOf(chains),
-    defaultChain: chains[0],
+    contractMapping: config_contractMapping,
+    defaultChain: config_defaultChain,
     ecosystem: ecosystem,
-    enableRawEvents: Stdlib_Option.getOr(publicConfig.rawEvents, false),
+    enableRawEvents: config_enableRawEvents,
     maxAddrInPartition: Env.maxAddrInPartition,
     clientFilterAddressThreshold: Env.clientFilterAddressThreshold,
-    batchSize: Stdlib_Option.getOr(publicConfig.fullBatchSize, 5000),
+    batchSize: config_batchSize,
     reorgThresholdReadyTolerance: 100,
     lowercaseAddresses: lowercaseAddresses,
-    isDev: Stdlib_Option.getOr(publicConfig.isDev, false),
+    isDev: config_isDev,
+    isolated: false,
     userEntitiesByName: userEntitiesByName,
     userEntities: userEntities,
-    allEnums: allEnums
+    allEnums: allEnums,
+    checkpointSequence: config_checkpointSequence
   };
-}
-
-function isIsolatedMultichain(config) {
-  if (ChainMap.keys(config.chainMap).length > 1) {
-    return config.userEntities.every(entityConfig => !entityConfig.crossChain);
+  let chainIds = publicConfig.isolatedChains;
+  if (chainIds !== undefined) {
+    return isolate(config, chainIds);
   } else {
-    return false;
+    return config;
   }
 }
 
@@ -853,36 +894,6 @@ function getEventConfig(config, contractName, eventName, chainId) {
   });
 }
 
-function shouldSaveHistory(config, isInReorgThreshold, chainId) {
-  if (config.shouldSaveFullHistory) {
-    return true;
-  } else if (config.shouldRollbackOnReorg && isInReorgThreshold) {
-    if (chainId !== undefined && isIsolatedMultichain(config)) {
-      return ChainMap.get(config.chainMap, Primitive_option.valFromOption(chainId)).maxReorgDepth > 0;
-    } else {
-      return true;
-    }
-  } else {
-    return false;
-  }
-}
-
-function shouldPruneHistory(config, isInReorgThreshold) {
-  if (!config.shouldSaveFullHistory && config.shouldRollbackOnReorg) {
-    return isInReorgThreshold;
-  } else {
-    return false;
-  }
-}
-
-function getChain(config, chainId) {
-  if (ChainMap.has(config.chainMap, chainId)) {
-    return chainId;
-  } else {
-    return Stdlib_JsError.throwWithMessage("No chain with id " + ChainId.toString(chainId) + " found in config.yaml");
-  }
-}
-
 let primedJson = {
   contents: undefined
 };
@@ -931,6 +942,7 @@ function stripSensitiveData(json) {
   };
   if (typeof cloned === "object" && cloned !== null && !Array.isArray(cloned)) {
     Utils.Dict.deleteInPlace(cloned, "isDev");
+    Utils.Dict.deleteInPlace(cloned, "isolatedChains");
     stripChains(cloned["evm"]);
     stripChains(cloned["fuel"]);
     stripChains(cloned["svm"]);
@@ -1159,14 +1171,12 @@ export {
   publicConfigStorageSchema,
   publicConfigSchema,
   contractMappingOf,
+  getChain,
+  isolate,
   fromPublic,
-  isIsolatedMultichain,
   normalizeUserAddress,
   normalizeSimulateAddress,
   getEventConfig,
-  shouldSaveHistory,
-  shouldPruneHistory,
-  getChain,
   prime,
   getPublicConfigJson,
   stripSensitiveData,

package/src/CrossChainState.res

@@ -8,13 +8,13 @@ type t = {
   // Chain ids in a stable order, so the cross-chain loops iterate the chains
   // without allocating a values array on every tick.
   chainIds: array<ChainId.t>,
-  // True once every chain has caught up to head/endBlock. Monotonic during a run.
+  // True once every chain this process drives has caught up to head/endBlock and
+  // the indexes they owe are committed. Monotonic during a run.
   mutable isRealtime: bool,
-  // True once every chain has caught up and there's nothing left to process,
-  // but before the deferred schema indexes and `ready_at` are committed. The
-  // gap between this and `isRealtime` is the FinalizingIndexes phase.
+  // True once those chains have caught up and there's nothing left to process,
+  // but before the deferred schema indexes and `ready_at` are committed. The gap
+  // between this and `isRealtime` is the FinalizingIndexes phase.
   mutable isCaughtUp: bool,
-  mutable isInReorgThreshold: bool,
   // Indexer-wide fetch buffer pool (item count), shared across all chains.
   targetBufferSize: int,
 }
@@ -26,18 +26,12 @@ let calculateTargetBufferSize = () =>
   | None => 100_000
   }
 
-let make = (
-  ~chainStates,
-  ~isInReorgThreshold,
-  ~isRealtime,
-  ~targetBufferSize=calculateTargetBufferSize(),
-): t => {
+let make = (~chainStates, ~isRealtime, ~targetBufferSize=calculateTargetBufferSize()): t => {
   {
     chainStates,
     chainIds: chainStates->Dict.valuesToArray->Array.map(cs => (cs->ChainState.chainConfig).id),
     isRealtime,
     isCaughtUp: isRealtime,
-    isInReorgThreshold,
     targetBufferSize,
   }
 }
@@ -51,10 +45,21 @@ let getChainState = (crossChainState: t, chainId) =>
 
 let chainStates = (crossChainState: t) => crossChainState.chainStates
 let isRealtime = (crossChainState: t) => crossChainState.isRealtime
+let chainIds = (crossChainState: t) => crossChainState.chainIds
 let isCaughtUp = (crossChainState: t) => crossChainState.isCaughtUp
-let isInReorgThreshold = (crossChainState: t) => crossChainState.isInReorgThreshold
+// Chains enter the threshold together. It is the run-wide reading; what a
+// write keeps is decided per chain.
+let isInReorgThreshold = (crossChainState: t) => {
+  let chainStates = crossChainState.chainStates->Dict.valuesToArray
+  chainStates->Utils.Array.notEmpty && chainStates->Array.every(ChainState.isInReorgThreshold)
+}
 let targetBufferSize = (crossChainState: t) => crossChainState.targetBufferSize
 
+// Whether each chain's writes still need history, keyed by chain id — what the
+// history policy is built from.
+let shouldSaveHistory = (crossChainState: t) =>
+  crossChainState.chainStates->Utils.Dict.mapValues(ChainState.shouldSaveHistory)
+
 // Ready-to-process items across every chain — the live draw against
 // targetBufferSize, which is a budget of processable events (items stuck behind
 // a gap don't count toward the goal of keeping ~targetBufferSize ready).
@@ -74,14 +79,20 @@ let nextItemIsNone = (crossChainState: t): bool =>
 
 // Each chain's safe checkpoint: the last one a reorg on that chain can no longer
 // reach, or None while it has nothing safe yet. A chain that can't be rolled
-// back (maxReorgDepth = 0) tracks none, and everything it has committed is safe.
-let getSafeCheckpointIdByChain = (crossChainState: t, ~committedCheckpointId) =>
+// back (maxReorgDepth = 0) tracks none, and everything committed is safe from
+// it: under one shared sequence that is the run's highest id, not the chain's
+// own — an idle chain's would hold every other chain's prune back.
+let getSafeCheckpointIdByChain = (
+  crossChainState: t,
+  ~sequence: CheckpointSequence.t,
+  ~committedFrontier,
+) =>
   crossChainState.chainIds->Array.map(chainId => {
     let cs = crossChainState->getChainState(chainId)
     (
       chainId,
       switch cs->ChainState.safeCheckpointTracking {
-      | None => Some(committedCheckpointId)
+      | None => Some(sequence->CheckpointSequence.position(committedFrontier, ~chainId))
       | Some(tracking) =>
         tracking->SafeCheckpointTracking.getSafeCheckpointId(
           ~sourceBlockNumber=cs->ChainState.knownHeight,
@@ -94,20 +105,16 @@ let getSafeCheckpointIdByChain = (crossChainState: t, ~committedCheckpointId) =>
 
 let createBatch = (
   crossChainState: t,
-  ~processedCheckpointId,
+  ~config: Config.t,
+  ~frontier,
   ~batchSizeTarget: int,
-  ~isRollback: bool,
 ): Batch.t => {
   Batch.make(
-    ~isInReorgThreshold=crossChainState.isInReorgThreshold,
-    ~checkpointIdBeforeBatch=processedCheckpointId->BigInt.add(
-      // Since for rollback we have a diff checkpoint id.
-      // This is needed to currectly overwrite old state
-      // in an append-only ClickHouse insert.
-      isRollback ? 1n : 0n,
-    ),
+    ~sequence=config.checkpointSequence,
+    ~history=config->HistoryPolicy.decide(~shouldSaveHistory=crossChainState->shouldSaveHistory),
+    ~frontier,
     ~chainsBeforeBatch=crossChainState.chainStates->Utils.Dict.mapValues(
-      ChainState.toChainBeforeBatch,
+      ChainState.toChainBeforeBatch(~isRealtime=crossChainState.isRealtime, ...),
     ),
     ~batchSizeTarget,
   )
@@ -123,8 +130,6 @@ let enterReorgThreshold = (crossChainState: t) => {
     ->getChainState(crossChainState.chainIds->Array.getUnsafe(i))
     ->ChainState.enterReorgThreshold
   }
-
-  crossChainState.isInReorgThreshold = true
 }
 
 // Commit each progressed chain's batch progress, then record whether the whole
@@ -146,17 +151,6 @@ let applyBatchProgress = (crossChainState: t, ~batch: Batch.t, ~blockTimestampNa
 
   crossChainState.isCaughtUp =
     crossChainState.isCaughtUp || (crossChainState->nextItemIsNone && everyChainCaughtUp.contents)
-
-  // A run resumed with every chain already stamped ready needs no finalize —
-  // the indexes were committed together with those stamps.
-  let allChainsReady = ref(true)
-  for i in 0 to chainIds->Array.length - 1 {
-    if !(crossChainState->getChainState(chainIds->Array.getUnsafe(i))->ChainState.isReady) {
-      allChainsReady := false
-    }
-  }
-
-  crossChainState.isRealtime = crossChainState.isRealtime || allChainsReady.contents
 }
 
 // Every chain has buffered up to its head (or endblock) with nothing
@@ -191,29 +185,25 @@ let markCaughtUpIfSettled = (crossChainState: t) =>
 // may have moved on — at which point no chain looks at head any more and the
 // indexes it still owes would wait out another whole backfill. Deciding here,
 // before any source request, keeps that debt tied to the progress that was
-// actually committed. Skipped once every chain carries `ready_at`: those indexes
-// were committed together with the stamps.
+// actually committed. Skipped when the run resumed realtime, which is exactly
+// the case where the indexes are already committed and nothing is owed.
 let markCaughtUpOnResume = (crossChainState: t) => {
   let everyChainCaughtUp = ref(crossChainState.chainIds->Array.length > 0)
-  let everyChainReady = ref(true)
   for i in 0 to crossChainState.chainIds->Array.length - 1 {
     let cs = crossChainState->getChainState(crossChainState.chainIds->Array.getUnsafe(i))
     if !(cs->ChainState.isDurablyCaughtUp) {
       everyChainCaughtUp := false
     }
-    if !(cs->ChainState.isReady) {
-      everyChainReady := false
-    }
   }
 
-  if everyChainCaughtUp.contents && !everyChainReady.contents && crossChainState->nextItemIsNone {
+  if everyChainCaughtUp.contents && !crossChainState.isRealtime && crossChainState->nextItemIsNone {
     crossChainState.isCaughtUp = true
   }
 }
 
-// Concludes the FinalizingIndexes phase: stamps every chain with the `ready_at`
-// already committed alongside the deferred schema indexes and switches the
-// indexer to realtime.
+// Concludes the FinalizingIndexes phase: stamps every chain this process drives
+// with the `ready_at` already committed alongside their deferred schema indexes,
+// and switches the indexer to realtime.
 let markReady = (crossChainState: t, ~readyAt) => {
   for i in 0 to crossChainState.chainIds->Array.length - 1 {
     crossChainState
@@ -267,6 +257,10 @@ let idleOrWaitAction = (cs: ChainState.t) =>
     ? FetchState.NothingToQuery
     : FetchState.WaitingForNewBlock
 
+// How far past the alignment anchor's frontier progress a follower may fetch,
+// as a fraction of its own alignable range.
+let alignmentMargin = 0.2
+
 // Dispatch a fetch tick across the whole indexer from one shared pool of
 // ~targetBufferSize ready events, as a waterfall: visit chains furthest-behind
 // first, hand each the budget remaining at that point (plus its own
@@ -350,11 +344,14 @@ let checkAndFetch = async (
         (isCold ? Pervasives.min(remaining.contents, coldChainBudget) : remaining.contents) +.
         cs->ChainState.pendingBudget
       let maxTargetBlock = switch alignment {
-      // 10% margin past the anchor's line: chains whose progress tracks the
+      // 20% margin past the anchor's line: chains whose progress tracks the
       // anchor closely would otherwise flap in and out of the clamp on every
-      // small frontier move, stalling their pipeline every other tick.
+      // small frontier move, stalling their pipeline every other tick. The
+      // margin is also the headroom a follower keeps buffered while the anchor
+      // is mid-fetch, so it has to outlast a slow anchor response, not just
+      // absorb frontier jitter.
       | Some((anchorChainId, progress)) if anchorChainId !== chainId =>
-        Some(cs->ChainState.blockAtProgress(~progress=progress +. 0.1))
+        Some(cs->ChainState.blockAtProgress(~progress=progress +. alignmentMargin))
       | _ => None
       }
       switch cs->ChainState.getNextQuery(~chainTargetItems, ~maxTargetBlock?) {
@@ -404,7 +401,7 @@ let checkAndFetch = async (
     switch actionByChain->ChainId.Dict.dangerouslyGetNonOption(chainId) {
     | Some(NothingToQuery)
     | None => ()
-    | Some(action) => promises->Array.push(dispatchChain(~chainId=chainId, ~action))
+    | Some(action) => promises->Array.push(dispatchChain(~chainId, ~action))
     }
   }
   let _ = await promises->Promise.all