@subsquid/ponder 0.15.17-sqd.1

package/src/sync-historical/portal-realtime-wire.ts

@@ -0,0 +1,389 @@
+/**
+ * Wiring glue: Portal-native realtime → Ponder's realtime runtime.
+ *
+ * `portal-realtime.ts` produces `PortalRealtimeEvent`s from the Portal `/stream`. THIS module adapts them
+ * into ponder's own `RealtimeSyncEvent`s and drops into `runtime/realtime.ts` as an alternative to the
+ * `rpc.subscribe`+`createRealtimeSync` path — so the downstream indexing/checkpointing is UNCHANGED.
+ *
+ * Everything here is inert unless a chain has a Portal source AND `PORTAL_REALTIME==="stream"`. When the
+ * flag is unset/"rpc", `isPortalRealtime()` is false and `clampFinalizedToPortalHead()` is a pass-through,
+ * so the RPC realtime path (the "A-path") is byte-for-byte unchanged.
+ *
+ * WHY the finality clamp: ponder computes `syncProgress.finalized` from RPC (`latest−finalityBlockCount`),
+ * which can sit ABOVE the Portal's finalized head. If realtime streamed from below that finalized block it
+ * would silently regress ponder's persisted checkpoints; if historical skipped its RPC finality-gap
+ * fallback it would mark the gap "synced" with no data (a permanent silent hole). Both are avoided by
+ * making the Portal's finalized head the finality boundary in stream mode: `clampFinalizedToPortalHead()`
+ * lowers `syncProgress.finalized` to the Portal head, so (a) historical stops exactly at the Portal head
+ * (no gap, the RPC fallback never triggers) and (b) realtime streams `[portal-head+1 → tip]` — every block
+ * strictly ABOVE `finalized`, and every `finalize` monotonically at/above it.
+ */
+import type { Common } from "@/internal/common.js";
+import type {
+  Chain,
+  EventCallback,
+  Factory,
+  FactoryId,
+  Filter,
+  LightBlock,
+  LogFilter,
+  SyncLog,
+} from "@/internal/types.js";
+import {
+  getChildAddress,
+  getFilterFactories,
+  isAddressFactory,
+  isLogFactoryMatched,
+} from "@/runtime/filter.js";
+import { eth_getBlockByNumber } from "@/rpc/actions.js";
+import type { Rpc } from "@/rpc/index.js";
+import type { RealtimeSyncEvent } from "@/sync-realtime/index.js";
+import { type Address, hexToNumber, numberToHex } from "viem";
+import {
+  type Light,
+  type PortalRealtimeEvent,
+  portalRealtimeEvents,
+} from "./portal-realtime.js";
+import { hx } from "./portal-transform.js";
+
+// ─────────────────────────────── flag / detection ───────────────────────────────
+
+/** True when this chain should use the Portal `/stream` for realtime instead of ponder's RPC path. */
+export const isPortalRealtime = (chain: { portal?: string | undefined }): boolean =>
+  typeof chain.portal === "string" && process.env.PORTAL_REALTIME === "stream";
+
+const portalHeaders = (): Record<string, string> => {
+  const h: Record<string, string> = { "content-type": "application/json", "accept-encoding": "gzip" };
+  if (process.env.PORTAL_API_KEY) h["x-api-key"] = process.env.PORTAL_API_KEY;
+  return h;
+};
+
+const cleanUrl = (portal: string): string => portal.replace(/\/$/, "");
+
+// ─────────────────────────────── Portal finalized head + finality clamp ───────────────────────────────
+
+/** Poll the Portal `/finalized-head` (reused by both the historical finality-gap decision and here). */
+export async function portalFinalizedHead(
+  portalUrl: string,
+  headers: Record<string, string>,
+  fetchImpl: typeof fetch = fetch,
+): Promise<number | undefined> {
+  try {
+    const h = await fetchImpl(`${cleanUrl(portalUrl)}/finalized-head`, { headers }).then((r) => r.json());
+    if (typeof h?.number === "number") return h.number;
+  } catch {
+    /* head unknown → caller stays conservative */
+  }
+  return undefined;
+}
+
+/**
+ * In stream mode, lower `finalizedBlock` to the Portal's finalized head (when the Portal lags ponder's
+ * RPC-derived finalized block). Pass-through for the A-path (no portal / flag off) and when the Portal is
+ * already at/ahead of the RPC finalized block — so it never RAISES the boundary. Called at every site that
+ * sets `syncProgress.finalized`: the initial `getLocalSyncProgress` and the backfill-cutover refetch.
+ */
+export async function clampFinalizedToPortalHead(params: {
+  chain: Chain;
+  rpc: Rpc;
+  finalizedBlock: LightBlock;
+  common?: Common;
+  fetchImpl?: typeof fetch;
+}): Promise<LightBlock> {
+  const { chain, rpc, finalizedBlock } = params;
+  if (isPortalRealtime(chain) === false) return finalizedBlock;
+
+  const portalUrl = cleanUrl(chain.portal!);
+  const head = await portalFinalizedHead(portalUrl, portalHeaders(), params.fetchImpl);
+  // Head unknown → stay conservative and keep the RPC finalized block (historical's own RPC finality-gap
+  // fallback remains the safety net). Portal at/ahead of RPC finalized → nothing to clamp.
+  if (head === undefined || head >= hexToNumber(finalizedBlock.number)) return finalizedBlock;
+
+  const clamped = (await eth_getBlockByNumber(rpc, [numberToHex(head), false], {
+    retryNullBlockRequest: true,
+  })) as unknown as LightBlock;
+  params.common?.logger.debug({
+    service: "portal",
+    msg: `Portal ${chain.name}: clamped realtime finalized ${hexToNumber(finalizedBlock.number)} → Portal head ${head} (stream mode)`,
+  });
+  return clamped;
+}
+
+// ─────────────────────────────── log-request construction (mirrors portal.ts) ───────────────────────────────
+
+/** Portal `/stream` log filter — same shape the historical sync uses. */
+export type PortalLogRequest = {
+  address?: string[];
+  topic0?: string[];
+  topic1?: string[];
+  topic2?: string[];
+  topic3?: string[];
+};
+
+const PORTAL_MAX_ADDRESSES = 1000;
+const asArr = <T,>(v: T | T[]): T[] => (Array.isArray(v) ? v : [v]);
+const lc = (a: string): string => a.toLowerCase();
+
+/** The unique factories referenced by any filter (deduped by id). */
+export const uniqueFactories = (eventCallbacks: { filter: Filter }[]): Factory[] =>
+  [
+    ...new Map(
+      eventCallbacks.flatMap((e) => getFilterFactories(e.filter)).map((f) => [f.id, f]),
+    ).values(),
+  ];
+
+/** Log-filter → Portal log requests. Factory-address filters expand to the currently-known children. */
+function logRequestsFor(
+  filter: LogFilter,
+  childAddresses: Map<FactoryId, Map<Address, number>>,
+): PortalLogRequest[] {
+  const base: PortalLogRequest = {};
+  if (filter.topic0) base.topic0 = asArr(filter.topic0);
+  if (filter.topic1) base.topic1 = asArr(filter.topic1 as any);
+  if (filter.topic2) base.topic2 = asArr(filter.topic2 as any);
+  if (filter.topic3) base.topic3 = asArr(filter.topic3 as any);
+  let addresses: string[] | undefined;
+  if (isAddressFactory(filter.address)) {
+    addresses = Array.from(childAddresses.get(filter.address.id)?.keys() ?? []);
+    if (addresses.length === 0) return []; // no children yet → nothing to request for this filter
+  } else if (filter.address === undefined) {
+    return [base];
+  } else {
+    addresses = asArr(filter.address).map(lc);
+  }
+  const out: PortalLogRequest[] = [];
+  for (let i = 0; i < addresses.length; i += PORTAL_MAX_ADDRESSES)
+    out.push({ ...base, address: addresses.slice(i, i + PORTAL_MAX_ADDRESSES) });
+  return out;
+}
+
+/** Collapse requests sharing the same address-set + topic1..3, unioning topic0 (keeps the body small). */
+function mergeLogRequests(reqs: PortalLogRequest[]): PortalLogRequest[] {
+  const groups = new Map<string, PortalLogRequest>();
+  for (const r of reqs) {
+    const key = JSON.stringify([r.address ? [...r.address].sort() : null, r.topic1 ?? null, r.topic2 ?? null, r.topic3 ?? null]);
+    const g = groups.get(key);
+    if (!g) { groups.set(key, { ...r, topic0: r.topic0 ? [...new Set(r.topic0)] : undefined }); continue; }
+    if (g.topic0 === undefined || r.topic0 === undefined) g.topic0 = undefined;
+    else { const s = new Set(g.topic0); for (const t of r.topic0) s.add(t); g.topic0 = [...s]; }
+  }
+  return [...groups.values()];
+}
+
+/**
+ * Build the merged Portal `/stream` log filter for a chain's realtime: every log filter's
+ * address+topics PLUS a discovery request per factory (factory address + ProxyCreated selector), so new
+ * children are streamed and pruned/matched downstream. Mirrors `portal.ts` so the realtime and historical
+ * fetch-specs agree.
+ */
+export function buildPortalLogRequests(
+  eventCallbacks: { filter: Filter }[],
+  childAddresses: Map<FactoryId, Map<Address, number>>,
+): PortalLogRequest[] {
+  const filters = eventCallbacks.map((e) => e.filter);
+  const reqs: PortalLogRequest[] = [];
+  for (const f of filters) if (f.type === "log") reqs.push(...logRequestsFor(f as LogFilter, childAddresses));
+  for (const factory of uniqueFactories(eventCallbacks)) {
+    const address = factory.address ? asArr(factory.address).map(lc) : undefined;
+    reqs.push({ address, topic0: [factory.eventSelector.toLowerCase()] });
+  }
+  return mergeLogRequests(reqs);
+}
+
+// ─────────────────────────────── factory child discovery ───────────────────────────────
+
+/**
+ * Discover factory children in a block's logs — reuses ponder's own factory logic (`isLogFactoryMatched`
+ * + `getChildAddress`). For the euler `ProxyCreated(address indexed proxy,…)` factory the child is the
+ * `proxy` in topic1. Returns the per-factory children found in THIS block (keyed by `Factory`, the shape
+ * `handleRealtimeSyncEvent` finalizes into the sync-store).
+ */
+export function discoverChildAddresses(
+  logs: SyncLog[],
+  factories: Factory[],
+): Map<Factory, Set<Address>> {
+  const out = new Map<Factory, Set<Address>>();
+  for (const factory of factories) {
+    for (const log of logs) {
+      if (isLogFactoryMatched({ factory, log }) === false) continue;
+      let address: Address;
+      try {
+        address = getChildAddress({ log, factory }).toLowerCase() as Address;
+      } catch {
+        continue; // ABI mismatch on a factory with no fixed address → skip (mirrors createRealtimeSync)
+      }
+      if (out.has(factory) === false) out.set(factory, new Set<Address>());
+      out.get(factory)!.add(address);
+    }
+  }
+  return out;
+}
+
+/**
+ * Fold this block's discovered children into the RUNNING `childAddresses` map (the one `buildEvents` reads
+ * to match factory-child logs) — so a child created in this block is matched for its own logs in the SAME
+ * block, exactly like `createRealtimeSync`. Returns true if any NEW child was added.
+ */
+function applyDiscovered(
+  discovered: Map<Factory, Set<Address>>,
+  childAddresses: Map<FactoryId, Map<Address, number>>,
+  blockNumber: number,
+): boolean {
+  let added = false;
+  for (const [factory, addresses] of discovered) {
+    let rec = childAddresses.get(factory.id);
+    if (rec === undefined) { rec = new Map<Address, number>(); childAddresses.set(factory.id, rec); }
+    for (const address of addresses) {
+      if (rec.has(address) === false) { rec.set(address, blockNumber); added = true; }
+    }
+  }
+  return added;
+}
+
+// ─────────────────────────────── event conversion ───────────────────────────────
+
+/** Portal `Light` (decimal number/timestamp) → ponder `LightBlock` (hex). */
+export const lightToLightBlock = (l: Light): LightBlock => ({
+  number: hx(l.number),
+  hash: l.hash as LightBlock["hash"],
+  parentHash: l.parentHash as LightBlock["parentHash"],
+  timestamp: hx(l.timestamp),
+});
+
+/**
+ * PortalRealtimeEvent → ponder RealtimeSyncEvent. `block` becomes a log-only BlockWithEventData (no
+ * txs/receipts/traces — euler is log-indexed); `reorg`/`finalize` pass through with hex LightBlocks.
+ */
+export function toRealtimeSyncEvent(
+  ev: PortalRealtimeEvent,
+  childAddresses: Map<Factory, Set<Address>>,
+): RealtimeSyncEvent {
+  switch (ev.type) {
+    case "block":
+      return {
+        type: "block",
+        hasMatchedFilter: ev.hasMatchedFilter,
+        block: ev.block,
+        logs: ev.logs,
+        transactions: [],
+        transactionReceipts: [],
+        traces: [],
+        childAddresses,
+        blockCallback: undefined, // no rpc.subscribe backpressure hook in the stream path (optional-chained downstream)
+      };
+    case "reorg":
+      return { type: "reorg", block: lightToLightBlock(ev.block), reorgedBlocks: ev.reorgedBlocks.map(lightToLightBlock) };
+    case "finalize":
+      return { type: "finalize", block: lightToLightBlock(ev.block) };
+  }
+}
+
+// ─────────────────────────────── drop-in realtime generator ───────────────────────────────
+
+/**
+ * Drop-in replacement for `getRealtimeEventGenerator` when `isPortalRealtime(chain)`. Yields the SAME
+ * `{chain, event: RealtimeSyncEvent}` stream, sourced from the Portal `/stream` instead of
+ * `rpc.subscribe`+`createRealtimeSync`. Callers (omni/multi/isolated) are unchanged.
+ */
+export async function* getPortalRealtimeEventGenerator(params: {
+  common: Common;
+  chain: Chain;
+  rpc: Rpc;
+  eventCallbacks: EventCallback[];
+  syncProgress: { finalized: LightBlock; end?: LightBlock | undefined };
+  childAddresses: Map<FactoryId, Map<Address, number>>;
+  fetchImpl?: typeof fetch; // injected for tests
+  finalizePollMs?: number; // injected for tests (prod: portal-realtime.ts default cadence)
+}) {
+  const { common, chain, eventCallbacks, syncProgress, childAddresses } = params;
+  const portalUrl = cleanUrl(chain.portal!);
+  const headers = portalHeaders();
+  const factories = uniqueFactories(eventCallbacks);
+
+  const startupFinalized = hexToNumber(syncProgress.finalized.number);
+  const fromBlock = startupFinalized + 1; // finalized == Portal head (clamped) → stream (portal-head, tip]
+  const endBlock = syncProgress.end ? hexToNumber(syncProgress.end.number) : undefined;
+
+  // Mutable: rebuilt (in place) whenever a new child is discovered so the next stream reconnection filters
+  // the new child's logs too (portal-realtime.ts re-reads this array when it re-opens the stream).
+  const logs = buildPortalLogRequests(eventCallbacks, childAddresses);
+
+  let childCount = 0;
+  for (const [, m] of childAddresses) childCount += m.size;
+  common.logger.info({
+    service: "portal",
+    msg: "Started live indexing (Portal /stream)",
+    chain: chain.name,
+    chain_id: chain.id,
+    finalized_block: startupFinalized,
+    factory_address_count: childCount,
+  });
+
+  const controller = new AbortController();
+  let lastFinalized = startupFinalized;
+  try {
+    for await (const ev of portalRealtimeEvents({
+      portalUrl,
+      headers,
+      fromBlock,
+      logs,
+      blockFields: BLOCK_FIELDS,
+      logFields: LOG_FIELDS,
+      finalizedHead: () => portalFinalizedHead(portalUrl, headers, params.fetchImpl),
+      finalizePollMs: params.finalizePollMs,
+      signal: controller.signal,
+      fetchImpl: params.fetchImpl,
+    })) {
+      if (ev.type === "finalize") {
+        // Q3 safety: never regress ponder's finalized/safe checkpoints. Suppress a finalize at/below the
+        // startup boundary or below one already emitted (Portal head only ever advances, so this is defensive).
+        const n = ev.block.number;
+        if (n <= startupFinalized || n <= lastFinalized) continue;
+        lastFinalized = n;
+        yield { chain, event: toRealtimeSyncEvent(ev, new Map()) };
+        continue;
+      }
+
+      if (ev.type === "reorg") {
+        yield { chain, event: toRealtimeSyncEvent(ev, new Map()) };
+        continue;
+      }
+
+      // block
+      const discovered = discoverChildAddresses(ev.logs, factories);
+      const blockNumber = hexToNumber(ev.block.number);
+      if (applyDiscovered(discovered, childAddresses, blockNumber)) {
+        const next = buildPortalLogRequests(eventCallbacks, childAddresses);
+        logs.length = 0;
+        logs.push(...next); // mutate in place — picked up on the next `/stream` reconnection
+      }
+
+      yield { chain, event: toRealtimeSyncEvent(ev, discovered) };
+
+      if (endBlock !== undefined && blockNumber >= endBlock) {
+        common.logger.info({
+          service: "portal",
+          msg: "Completed live indexing (chain end block has been indexed)",
+          chain: chain.name,
+          chain_id: chain.id,
+          end_block: endBlock,
+        });
+        return;
+      }
+    }
+  } finally {
+    controller.abort();
+  }
+}
+
+// Block header fields — the RPC-path-equivalent set (kept in sync with portal.ts) so stored realtime
+// blocks are byte-consistent with the historical Portal backfill.
+const BLOCK_FIELDS: Record<string, boolean> = {
+  number: true, hash: true, parentHash: true, timestamp: true, logsBloom: true, miner: true,
+  gasUsed: true, gasLimit: true, stateRoot: true, receiptsRoot: true, transactionsRoot: true,
+  size: true, difficulty: true, extraData: true, baseFeePerGas: true, nonce: true, mixHash: true,
+  sha3Uncles: true, totalDifficulty: true,
+};
+const LOG_FIELDS: Record<string, boolean> = {
+  address: true, topics: true, data: true, transactionHash: true, transactionIndex: true, logIndex: true,
+};

package/src/sync-historical/portal-realtime.ts

@@ -0,0 +1,209 @@
+/**
+ * Portal-native realtime — serve `[portal-finalized-head → tip]` from the Portal `/stream` (fork-aware
+ * hot-blocks) instead of RPC.
+ *
+ * WHY: in realtime mode the fork currently backfills `[deploy → portal-finalized-head]` from the Portal,
+ * then fetches `[portal-finalized-head → chain-finalized-head]` over RPC (the "finality gap") and runs
+ * ponder's RPC RealtimeSync for the tip. For dense chains under multichain load that RPC gap-fetch stalls
+ * — ponder's single-thread global ordering blocks on the slowest chain's gap. The Portal already holds
+ * these hot-blocks; streaming them removes the RPC gap at its source.
+ *
+ * HOW: `/stream` with `includeAllBlocks:true` yields EVERY block header (a consecutive parentHash chain,
+ * for reorg tracking) plus the filtered euler logs, in one request. We reconcile each block into a local
+ * unfinalized chain and emit ponder's own `RealtimeSyncEvent`s (`block` / `reorg` / `finalize`) reusing
+ * `portal-transform` — so the downstream indexing + checkpointing in runtime/realtime.ts is UNCHANGED.
+ *
+ * The reorg/finalize reconciliation is pure + unit-tested; the `/stream` read and `/finalized-head` poll
+ * are the I/O shell.
+ */
+import type { SyncBlockHeader, SyncLog } from "@/internal/types.js";
+import { hexToNumber, type Hex } from "viem";
+import { hx, toSyncBlockHeader, toSyncLog, type RawHeader } from "./portal-transform.js";
+
+// ─────────────────────────────── pure reorg / finalize core (unit-tested) ───────────────────────────────
+
+/** The minimum a block needs for chain reconciliation. `number` is a decimal string (Portal-native). */
+export type Light = { number: number; hash: string; parentHash: string; timestamp: number };
+
+export type Reconcile =
+  | { kind: "append" } //   extends the tip (normal case)
+  | { kind: "duplicate" } // already the tip (idempotent re-delivery)
+  | { kind: "reorg"; commonAncestor: Light; reorgedBlocks: Light[] } // forks off an earlier block
+  | { kind: "gap" }; //     parent is unknown (beyond our window / a skipped block) → caller must re-sync
+
+/**
+ * Reconcile a newly-streamed block against the local unfinalized chain (oldest→newest, linked
+ * parentHash→hash). Pure. With `includeAllBlocks` the happy path is always `append`; a reorg re-streams
+ * from the fork point, so the new block's `parentHash` matches an EARLIER block — everything after that
+ * common ancestor is reorged.
+ */
+export function reconcile(unfinalized: Light[], next: Light): Reconcile {
+  if (unfinalized.length === 0) return { kind: "append" };
+  const tip = unfinalized[unfinalized.length - 1]!;
+  if (next.hash === tip.hash) return { kind: "duplicate" };
+  if (next.parentHash === tip.hash) return { kind: "append" };
+  const idx = unfinalized.findIndex((b) => b.hash === next.parentHash);
+  if (idx === -1) return { kind: "gap" };
+  return { kind: "reorg", commonAncestor: unfinalized[idx]!, reorgedBlocks: unfinalized.slice(idx + 1) };
+}
+
+/** Split the unfinalized chain at a newly-finalized block number. Pure. */
+export function takeFinalized(
+  unfinalized: Light[],
+  finalizedNumber: number,
+): { finalizedTip: Light | undefined; remaining: Light[] } {
+  let finalizedTip: Light | undefined;
+  const remaining: Light[] = [];
+  for (const b of unfinalized) {
+    if (b.number <= finalizedNumber) finalizedTip = b;
+    else remaining.push(b);
+  }
+  return { finalizedTip, remaining };
+}
+
+export const toLight = (h: RawHeader): Light => ({
+  number: h.number,
+  hash: h.hash,
+  parentHash: h.parentHash,
+  timestamp: h.timestamp,
+});
+
+// ─────────────────────────────── /stream I/O shell ───────────────────────────────
+
+export type PortalRealtimeArgs = {
+  portalUrl: string;
+  headers: Record<string, string>;
+  /** first block to stream (exclusive of already-indexed finalized head): syncProgress.finalized.number + 1 */
+  fromBlock: number;
+  /** euler log filters (address/topics), already merged — passed straight into the Portal query */
+  logs: Array<Record<string, unknown>>;
+  /** the block header fields ponder needs */
+  blockFields?: Record<string, boolean>;
+  logFields?: Record<string, boolean>;
+  signal?: AbortSignal;
+  fetchImpl?: typeof fetch;
+};
+
+/**
+ * Stream fork-aware hot-blocks with `includeAllBlocks` (every header + filtered logs). Yields raw Portal
+ * batch objects `{ header, logs }`. Re-opens the stream from the last seen block on disconnect so it runs
+ * continuously; a reorg simply re-streams from the fork point (reconcile() detects it).
+ */
+export async function* streamHotBlocks(
+  args: PortalRealtimeArgs,
+): AsyncGenerator<{ header: RawHeader; logs: any[] }> {
+  const fetchImpl = args.fetchImpl ?? fetch;
+  let cursor = args.fromBlock;
+  for (;;) {
+    if (args.signal?.aborted) return;
+    const body = JSON.stringify({
+      type: "evm",
+      fromBlock: cursor,
+      includeAllBlocks: true,
+      fields: {
+        block: args.blockFields ?? { number: true, hash: true, parentHash: true, timestamp: true },
+        log: args.logFields ?? { address: true, topics: true, data: true, logIndex: true, transactionHash: true, transactionIndex: true },
+      },
+      logs: args.logs,
+    });
+    let res: Response;
+    try {
+      res = await fetchImpl(`${args.portalUrl}/stream`, { method: "POST", headers: { "content-type": "application/json", ...args.headers }, body, signal: args.signal });
+    } catch {
+      await sleep(1000, args.signal);
+      continue;
+    }
+    if (res.status === 204 || !res.body) { await sleep(500, args.signal); continue; } // no hot data yet; re-poll
+    if (!res.ok) { await sleep(1000, args.signal); continue; }
+    const reader = res.body.getReader();
+    const dec = new TextDecoder();
+    let buf = "";
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += dec.decode(value, { stream: true });
+        let nl: number;
+        while ((nl = buf.indexOf("\n")) >= 0) {
+          const line = buf.slice(0, nl);
+          buf = buf.slice(nl + 1);
+          if (!line) continue;
+          const batch = JSON.parse(line);
+          if (batch?.header?.number != null) {
+            cursor = batch.header.number + 1; // resume past this block on reconnect
+            yield { header: batch.header, logs: batch.logs ?? [] };
+          }
+        }
+      }
+    } catch {
+      /* stream cut — reconnect from cursor */
+    }
+    await sleep(200, args.signal);
+  }
+}
+
+const sleep = (ms: number, signal?: AbortSignal) =>
+  new Promise<void>((resolve) => {
+    if (signal?.aborted) return resolve();
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => { clearTimeout(t); resolve(); }, { once: true });
+  });
+
+// ─────────────────────────────── event producer ───────────────────────────────
+// Emits ponder RealtimeSyncEvent-shaped objects. `finalizedHead()` polls the Portal finalized head so we
+// can emit `finalize` events (the RPC RealtimeSync derives finality from confirmations; the Portal tells
+// us directly). NB: the exact ponder BlockWithEventData construction (transactions/receipts/traces/
+// childAddresses) is completed at the wiring step in runtime/realtime.ts, which already has the factory
+// child-address maps + buildEvents; here we surface the block header + logs + reorg/finalize control flow.
+
+export type PortalRealtimeEvent =
+  | { type: "block"; block: SyncBlockHeader; logs: SyncLog[]; hasMatchedFilter: boolean }
+  | { type: "reorg"; block: Light; reorgedBlocks: Light[] }
+  | { type: "finalize"; block: Light };
+
+export async function* portalRealtimeEvents(
+  args: PortalRealtimeArgs & { finalizedHead: () => Promise<number | undefined>; finalizePollMs?: number },
+): AsyncGenerator<PortalRealtimeEvent> {
+  const unfinalized: Light[] = [];
+  let lastFinalizePoll = 0;
+  const pollMs = args.finalizePollMs ?? 4000;
+
+  for await (const { header, logs } of streamHotBlocks(args)) {
+    const light = toLight(header);
+    const r = reconcile(unfinalized, light);
+    if (r.kind === "duplicate") continue;
+    if (r.kind === "gap") {
+      // parent unknown: our window is behind a deeper reorg. Drop to a resync by clearing and continuing
+      // from this block (the finalized floor still protects already-committed data).
+      unfinalized.length = 0;
+    } else if (r.kind === "reorg") {
+      // trim the local chain and surface the rollback to the common ancestor
+      while (unfinalized.length && unfinalized[unfinalized.length - 1]!.number > r.commonAncestor.number) unfinalized.pop();
+      yield { type: "reorg", block: r.commonAncestor, reorgedBlocks: r.reorgedBlocks };
+    }
+    unfinalized.push(light);
+
+    const block = toSyncBlockHeader(header);
+    const syncLogs = logs.map((l) => toSyncLog(l, header));
+    yield { type: "block", block, logs: syncLogs, hasMatchedFilter: syncLogs.length > 0 };
+
+    // finalize on a cadence (cheap head probe), not every block
+    const now = Date.now();
+    if (now - lastFinalizePoll >= pollMs) {
+      lastFinalizePoll = now;
+      const fh = await args.finalizedHead().catch(() => undefined);
+      if (fh !== undefined) {
+        const { finalizedTip, remaining } = takeFinalized(unfinalized, fh);
+        if (finalizedTip) {
+          unfinalized.length = 0;
+          unfinalized.push(...remaining);
+          yield { type: "finalize", block: finalizedTip };
+        }
+      }
+    }
+  }
+}
+
+export { hx as _hx };
+export type { SyncBlockHeader, SyncLog, Hex };
+export { hexToNumber };