@effectstream/runtime 0.100.26 → 0.100.27

package/README.md

@@ -84,11 +84,21 @@ default:
 EFFECTSTREAM_COALESCE_EMPTY_BLOCKS=true
 ```
 
+The lag threshold that defines "behind the chain tip" defaults to **20× the
+main clock's block time** (falling back to 60 s when no `blockTimeMS` is
+exposed by the network config). Override it with
+`EFFECTSTREAM_LAG_THRESHOLD_MS` (milliseconds), e.g. for chains whose main
+clock fires faster than the runtime can keep up with one transaction per block:
+
+```bash
+EFFECTSTREAM_LAG_THRESHOLD_MS=30000   # engage coalescing past 30 s of lag
+```
+
 Behavior and guarantees:
 
 - **Catch-up only.** Coalescing engages only while behind the chain tip
-  (`now - block.timestamp` greater than 10× the main clock's block time) and
-  disengages at the tip, so steady-state stays one block per transaction.
+  (`now - block.timestamp` greater than the lag threshold) and disengages at
+  the tip, so steady-state stays one block per transaction.
 - **Identical database.** A coalesced sync produces a byte-for-byte identical
   database to a non-coalesced one. Empty blocks already never advance the block
   hash or RNG seed, so only the endpoint's block row and the per-protocol resume

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/runtime",
-  "version": "0.100.26",
+  "version": "0.100.27",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -13,17 +13,17 @@
   },
   "exports": "./src/mod.ts",
   "dependencies": {
-    "@effectstream/concise": "0.100.26",
-    "@effectstream/config": "0.100.26",
-    "@effectstream/coroutine": "0.100.26",
-    "@effectstream/crypto": "0.100.26",
-    "@effectstream/db": "0.100.26",
-    "@effectstream/event-client": "0.100.26",
-    "@effectstream/event-server": "0.100.26",
-    "@effectstream/log": "0.100.26",
-    "@effectstream/sm": "0.100.26",
-    "@effectstream/sync": "0.100.26",
-    "@effectstream/utils": "0.100.26",
+    "@effectstream/concise": "0.100.27",
+    "@effectstream/config": "0.100.27",
+    "@effectstream/coroutine": "0.100.27",
+    "@effectstream/crypto": "0.100.27",
+    "@effectstream/db": "0.100.27",
+    "@effectstream/event-client": "0.100.27",
+    "@effectstream/event-server": "0.100.27",
+    "@effectstream/log": "0.100.27",
+    "@effectstream/sm": "0.100.27",
+    "@effectstream/sync": "0.100.27",
+    "@effectstream/utils": "0.100.27",
     "@fastify/cors": "^11.0.1",
     "@metamask/json-rpc-engine": "^10.0.3",
     "pg": "8.21.0",

package/src/coalesce.ts

@@ -1,7 +1,7 @@
 /** Empty-block coalescing during deep catch-up: fold consecutive no-op blocks into one transaction. */
 import type { ChainBlock } from "@effectstream/sync";
 import { call, type Operation, race, sleep, until } from "effection";
-import type { Pool, PoolClient } from "pg";
+import type { Client, Pool, PoolClient } from "pg";
 import {
   acquireDBMutex,
   blockHeightDone,
@@ -21,6 +21,7 @@ import { ComponentNames, log, SeverityNumber } from "@effectstream/log";
 import { generateEffectstreamBlockHash, Prando } from "@effectstream/crypto";
 import type { EffectstreamBlockHash } from "@effectstream/utils";
 import type { DBMigrations } from "@effectstream/runtime";
+import { mergeCoalescingBoundaries } from "@effectstream/sync";
 
 /** Scheduled-input boundaries sampled once at run start (stable until the next non-empty block). */
 export type EmptyRunBoundaries = {
@@ -44,14 +45,53 @@ export function* loadEmptyRunBoundaries(
   const minScheduledBlockHeight = bh?.min_block_height != null && bh.min_block_height >= fromBlockNumber
     ? bh.min_block_height
     : null;
+  const minScheduledTimestampMs = ts?.min_timestamp != null
+    ? new Date(ts.min_timestamp).getTime()
+    : null;
+
+  mergeCoalescingBoundaries.minScheduledBlockHeight = minScheduledBlockHeight;
+  mergeCoalescingBoundaries.minScheduledTimestampMs = minScheduledTimestampMs;
+
   return {
     minScheduledBlockHeight,
-    minScheduledTimestampMs: ts?.min_timestamp != null
-      ? new Date(ts.min_timestamp).getTime()
-      : null,
+    minScheduledTimestampMs,
   };
 }
 
+/**
+ * Seed {@link mergeCoalescingBoundaries} once at startup so the merge loop knows
+ * which empty blocks it may coalesce before the runtime has applied any block.
+ * `loadEmptyRunBoundaries` keeps these in sync afterwards on each non-empty block.
+ *
+ * @param fromBlockNumber the next block height to apply (lastBlockHeight + 1);
+ *        scheduled heights below this are stale and ignored (see {@link loadEmptyRunBoundaries}).
+ */
+export function* initMergeCoalescingBoundaries(
+  dbConn: Pool | Client,
+  fromBlockNumber: number,
+  migrations: DBMigrations[] | undefined,
+): Operation<void> {
+  const [bh] = yield* until(getEarliestScheduledBlockHeight.run(undefined, dbConn));
+  const [ts] = yield* until(getEarliestScheduledTimestamp.run(undefined, dbConn));
+  const minScheduledBlockHeight = bh?.min_block_height != null && bh.min_block_height >= fromBlockNumber
+    ? bh.min_block_height
+    : null;
+  const minScheduledTimestampMs = ts?.min_timestamp != null
+    ? new Date(ts.min_timestamp).getTime()
+    : null;
+
+  const migrationBlockHeights: number[] = [];
+  for (const m of migrations ?? []) {
+    if (m.blockHeight != null) {
+      migrationBlockHeights.push(m.blockHeight);
+    }
+  }
+
+  mergeCoalescingBoundaries.minScheduledBlockHeight = minScheduledBlockHeight;
+  mergeCoalescingBoundaries.minScheduledTimestampMs = minScheduledTimestampMs;
+  mergeCoalescingBoundaries.migrationBlockHeights = migrationBlockHeights;
+}
+
 /** Mirrors the empty-block checks in process-blocks.ts without DB/STF work. */
 export function isCoalescableEmptyBlock(
   value: ChainBlock,

package/src/finalized-stream.ts

@@ -20,6 +20,7 @@ import {
   finalizedStreamStatus,
   recordConsumed,
   recordProduced,
+  recordCoalesced,
 } from "./api/stream-status.ts";
 import type { FinalizedBlockSubscription } from "./coalesce.ts";
 
@@ -52,6 +53,9 @@ export function* createBoundedFinalizedStream(
         yield* drained.wait();
       }
       recordProduced();
+      if (block.coalescedCount && block.coalescedCount > 1) {
+        recordCoalesced(block.coalescedCount - 1);
+      }
       yield* channel.send(block);
     },
   };

package/src/main.ts

@@ -33,7 +33,10 @@ import {
   type PendingEvent,
   processFinalizedBlockWithRetry,
 } from "./process-blocks.ts";
-import { createEmptyBlockCoalescer } from "./coalesce.ts";
+import {
+  createEmptyBlockCoalescer,
+  initMergeCoalescingBoundaries,
+} from "./coalesce.ts";
 import { startHttpServer } from "./api/http-server.ts";
 import { recordAppliedBlock } from "./api/apply-status.ts";
 import { recordCoalesced } from "./api/stream-status.ts";
@@ -96,14 +99,15 @@ export function* start(config: StartConfig): Operation<void> {
     );
   });
 
-  // 10× main clock block time (NTP if present, else protocol 0).
+  // 20× main clock block time (NTP if present, else protocol 0).
   // Falls back to 60 s so coalescing is not silently disabled for chains that
   // don't expose a blockTimeMS on their network config (e.g. Midnight-as-main).
   const ntpConfig = syncInfo.find(s => s.networkType === ConfigNetworkType.NTP);
   const clockBlockTimeMS =
     (ntpConfig?.network as { blockTimeMS?: number } | undefined)?.blockTimeMS ??
     (syncInfo[0]?.network as { blockTimeMS?: number } | undefined)?.blockTimeMS;
-  const lagThresholdMs = clockBlockTimeMS != null ? clockBlockTimeMS * 10 : 60_000;
+  const lagThresholdMs = ENV.EFFECTSTREAM_LAG_THRESHOLD_MS ??
+    (clockBlockTimeMS != null ? clockBlockTimeMS * 20 : 60_000);
 
   // Bounded hand-off queue between the merge and the apply loop. Backpressure caps
   // the in-memory queue so deep catch-up can't grow it toward the whole backlog
@@ -355,6 +359,9 @@ function* startup(
       viewStrategy,
     );
 
+    // Seed the merge loop's coalescing boundaries before any block is produced.
+    yield* initMergeCoalescingBoundaries(dbConn, lastBlockHeight + 1, config.migrations);
+
     return syncProtocols;
   } finally {
     releaseDBMutex(`startup-node`);