ponder-with-flashblocks 0.16.3

package/src/ui/app.ts

@@ -0,0 +1,207 @@
+import type {
+  getAppProgress,
+  getIndexingProgress,
+  getSyncProgress,
+} from "@/internal/metrics.js";
+import { formatEta, formatPercentage } from "@/utils/format.js";
+import pc from "picocolors";
+
+export type UiState = {
+  port: number;
+  hostname: string;
+  sync: Awaited<ReturnType<typeof getSyncProgress>>;
+  indexing: Awaited<ReturnType<typeof getIndexingProgress>>;
+  app: Awaited<ReturnType<typeof getAppProgress>>;
+};
+
+export const initialUiState: UiState = {
+  port: 42069,
+  hostname: "localhost",
+  sync: [],
+  indexing: {
+    hasError: false,
+    events: [],
+  },
+  app: {
+    progress: 0,
+    eta: undefined,
+    mode: undefined,
+  },
+};
+
+const buildProgressBar = (current: number, end: number, width = 48): string => {
+  const fraction = current / end;
+  const count = Math.min(Math.floor(width * fraction), width);
+  return "█".repeat(count) + "░".repeat(width - count);
+};
+
+export const buildTable = (
+  rows: { [key: string]: any }[],
+  columns: {
+    title: string;
+    key: string;
+    align: "left" | "right" | string;
+    format?: (value: any, row: { [key: string]: any }) => string | number;
+    maxWidth?: number;
+  }[],
+): string[] => {
+  if (rows.length === 0) {
+    return ["Waiting to start..."];
+  }
+
+  // Calculate column widths
+  const DEFAULT_MAX_COLUMN_WIDTH = 24;
+  const columnWidths = columns.map((column) => {
+    const formattedRows = rows.map((row) => {
+      const value = column.format
+        ? column.format(row[column.key], row)
+        : row[column.key];
+      return value !== undefined ? String(value) : "";
+    });
+
+    const maxWidth = Math.max(
+      ...formattedRows.map((val) => val.toString().length),
+      column.title.length,
+    );
+    return Math.min(maxWidth, column.maxWidth ?? DEFAULT_MAX_COLUMN_WIDTH);
+  });
+
+  // Generate header row
+  const headerRow = [
+    "│ ",
+    columns
+      .map((col, i) => {
+        const width = columnWidths[i] ?? 0;
+        return col.title
+          .padEnd(width, " ")
+          .padStart(col.align === "right" ? width : width, " ");
+      })
+      .join(" │ "),
+    " │",
+  ].join("");
+
+  // Generate separator
+  const separator = [
+    "├─",
+    columnWidths.map((w) => "─".repeat(w)).join("─┼─"),
+    "─┤",
+  ].join("");
+
+  // Generate data rows
+  const dataRows = rows.map((row) => {
+    return [
+      "│ ",
+      columns
+        .map((col, i) => {
+          const width = columnWidths[i] ?? 0;
+          const value = col.format
+            ? col.format(row[col.key], row)
+            : row[col.key];
+          const strValue = value !== undefined ? String(value) : "";
+          return col.align === "right"
+            ? strValue.padStart(width, " ")
+            : strValue.padEnd(width, " ");
+        })
+        .join(" │ "),
+      " │",
+    ].join("");
+  });
+
+  return [headerRow, separator, ...dataRows];
+};
+
+export const buildUiLines = (ui: UiState): string[] => {
+  const { sync, indexing, app, port, hostname } = ui;
+  const lines: string[] = [];
+
+  lines.push("");
+
+  if (indexing.hasError) {
+    lines.push(
+      pc.cyan("Resolve the error and save your changes to reload the server."),
+    );
+    return lines;
+  }
+
+  lines.push(pc.bold("Chains"));
+  lines.push("");
+
+  if (sync.length === 0) {
+    lines.push("Waiting to start...");
+  } else {
+    lines.push(
+      ...buildTable(sync, [
+        {
+          title: "Chain",
+          key: "chainName",
+          align: "left",
+        },
+        {
+          title: "Status",
+          key: "status",
+          align: "left",
+          format: (_, row) =>
+            row.status === "backfill"
+              ? `${row.status} (${formatPercentage(row.progress)})`
+              : row.status,
+        },
+        {
+          title: "Block",
+          key: "block",
+          align: "right",
+        },
+        {
+          title: "RPC (req/s)",
+          key: "rps",
+          align: "right",
+          format: (_, row) => row.rps.toFixed(1),
+        },
+      ]),
+    );
+  }
+
+  lines.push("");
+  let indexingLabel = pc.bold("Indexing");
+  if (app.mode !== undefined && app.progress !== 0) {
+    const color = app.mode === "backfill" ? "yellowBright" : "greenBright";
+    indexingLabel += ` (${pc[color](app.mode)})`;
+  }
+  lines.push(indexingLabel);
+  lines.push("");
+
+  if (indexing.events.length === 0) {
+    lines.push("Waiting to start...");
+  } else {
+    lines.push(
+      ...buildTable(indexing.events, [
+        { title: "Event", key: "eventName", align: "left", maxWidth: 36 },
+        { title: "Count", key: "count", align: "right" },
+        {
+          title: "Duration (ms)",
+          key: "averageDuration",
+          align: "right",
+          format: (v) => (v > 0 ? (v < 0.001 ? "<0.001" : v.toFixed(3)) : "-"),
+        },
+      ]),
+    );
+  }
+
+  if (app.mode !== "live") {
+    const progressValue = app.progress ?? 0;
+    const progressBar = buildProgressBar(progressValue, 1, 48);
+    let progressText = `${progressBar} ${formatPercentage(progressValue)}`;
+
+    if (app.eta !== undefined && app.eta !== 0) {
+      progressText += ` (${formatEta(app.eta * 1_000)} eta)`;
+    }
+
+    lines.push("");
+    lines.push(progressText);
+  }
+
+  lines.push("");
+  lines.push(pc.bold("API endpoints"));
+  lines.push(`Live at http://${hostname}:${port}`);
+
+  return lines;
+};

package/src/ui/index.ts

@@ -0,0 +1,37 @@
+import type { Common } from "@/internal/common.js";
+import {
+  getAppProgress,
+  getIndexingProgress,
+  getSyncProgress,
+} from "@/internal/metrics.js";
+import { buildUiLines, initialUiState } from "./app.js";
+import { patchWriteStreams } from "./patch.js";
+
+export function createUi({ common }: { common: Common }) {
+  const ui = initialUiState;
+
+  const { refresh, shutdown } = patchWriteStreams({
+    getLines: () => buildUiLines(ui),
+  });
+
+  // Update the UI state every 100ms (independent of write rate)
+  const stateUpdateInterval = setInterval(async () => {
+    ui.sync = await getSyncProgress(common.metrics);
+    ui.indexing = await getIndexingProgress(common.metrics);
+    ui.app = await getAppProgress(common.metrics);
+
+    if (common.options.hostname) ui.hostname = common.options.hostname;
+    if (common.metrics.port) ui.port = common.metrics.port;
+  }, 100);
+
+  // Refresh the UI every 32ms
+  const refreshInterval = setInterval(() => {
+    refresh();
+  }, 32);
+
+  common.buildShutdown.add(() => {
+    clearInterval(stateUpdateInterval);
+    clearInterval(refreshInterval);
+    shutdown();
+  });
+}

package/src/ui/patch.ts

@@ -0,0 +1,204 @@
+import util from "node:util";
+import ansi from "ansi-escapes";
+import terminalSize from "terminal-size";
+
+export function patchWriteStreams({ getLines }: { getLines: () => string[] }) {
+  const isBun = "bun" in process.versions;
+  const originalStdoutWrite = process.stdout.write;
+  const originalStderrWrite = process.stderr.write;
+
+  let isWriting = false;
+  let previousLineCount = 0;
+
+  let terminalWidth = terminalSize().columns;
+
+  const calculateLineCount = (lines: string[]): number => {
+    let count = 0;
+
+    // For each line, calculate how many terminal lines it will occupy
+    for (const line of lines) {
+      // Apply wrapping logic to get actual number of lines
+      const visibleLength = line.replaceAll(ansiEscapeRegex, "").length;
+      count += Math.max(1, Math.ceil(visibleLength / terminalWidth));
+    }
+
+    return count;
+  };
+
+  // Clear previous UI and render new UI
+  const clearAndWriteLines = (lines: string[]) => {
+    if (isWriting && !lines) return;
+
+    const wasAlreadyWriting = isWriting;
+    if (!wasAlreadyWriting) isWriting = true;
+
+    try {
+      const text = [...lines, ""].join("\n"); // Include trailing newline
+
+      // Calculate line count after constructing the text to ensure accuracy
+      const newLineCount = calculateLineCount(lines);
+
+      // Move cursor up to the start of the previous UI
+      if (previousLineCount > 0) {
+        originalStdoutWrite.call(
+          process.stdout,
+          ansi.cursorUp(previousLineCount),
+        );
+      }
+      // Clear all lines of the previous UI and below
+      originalStdoutWrite.call(process.stdout, ansi.eraseDown);
+      // Write the new UI
+      originalStdoutWrite.call(process.stdout, text);
+
+      previousLineCount = newLineCount;
+    } finally {
+      if (!wasAlreadyWriting) isWriting = false;
+    }
+  };
+
+  // Monkey patch stdout and stderr to handle out-of-band output
+  const handleOutput = function (
+    this: NodeJS.WriteStream,
+    buffer: string | Uint8Array,
+    encoding?: BufferEncoding,
+    cb?: (err?: Error) => void,
+  ) {
+    const originalWrite =
+      this === process.stderr ? originalStderrWrite : originalStdoutWrite;
+
+    // If we're already writing, use the original to avoid recursion
+    if (isWriting) {
+      return originalWrite.apply(this, [buffer, encoding, cb]);
+    }
+
+    // Clear the UI
+    if (previousLineCount > 0) {
+      originalStdoutWrite.call(
+        process.stdout,
+        ansi.cursorUp(previousLineCount) + ansi.eraseDown,
+      );
+      previousLineCount = 0;
+    }
+
+    // Write the new content
+    const result = originalWrite.apply(this, [buffer, encoding, cb]);
+
+    // Clear and write the latest UI below the new content
+    const lines = getLines();
+    clearAndWriteLines(lines);
+
+    return result;
+  };
+  process.stdout.write = handleOutput as typeof process.stdout.write;
+  process.stderr.write = handleOutput as typeof process.stderr.write;
+
+  // On terminal resize, reset terminal width and force a re-render
+  const resizeListener = () => {
+    terminalWidth = terminalSize().columns;
+
+    // Clear the UI
+    if (previousLineCount > 0) {
+      originalStdoutWrite.call(
+        process.stdout,
+        ansi.cursorUp(previousLineCount) + ansi.eraseDown,
+      );
+      previousLineCount = 0;
+    }
+
+    // Clear and write the latest UI
+    const lines = getLines();
+    clearAndWriteLines(lines);
+  };
+  process.stdout.on("resize", resizeListener);
+
+  let shutdown: () => void;
+
+  if (isBun) {
+    // bun has a custom impl of console.* methods that do not use process.stdout/process.stderr
+    // so need to patch them as well
+    const originalConsoleLog = console.log;
+    const originalConsoleInfo = console.info;
+    const originalConsoleWarn = console.warn;
+    const originalConsoleError = console.error;
+    const makeConsoleWriter =
+      (stream: NodeJS.WriteStream, _: typeof originalStdoutWrite) =>
+      (...args: unknown[]) => {
+        // biome-ignore lint/style/useTemplate:
+        const formatted = util.format(...args) + "\n";
+
+        // handleOutput so TUI is cleared + re-rendered
+        handleOutput.call(stream, formatted, "utf8", undefined);
+      };
+
+    console.log = makeConsoleWriter(
+      process.stdout,
+      originalStdoutWrite,
+    ) as typeof console.log;
+    console.info = makeConsoleWriter(
+      process.stdout,
+      originalStdoutWrite,
+    ) as typeof console.info;
+    console.warn = makeConsoleWriter(
+      process.stderr,
+      originalStderrWrite,
+    ) as typeof console.warn;
+    console.error = makeConsoleWriter(
+      process.stderr,
+      originalStderrWrite,
+    ) as typeof console.error;
+
+    shutdown = () => {
+      // Restore original write methods
+      process.stdout.write = originalStdoutWrite;
+      process.stderr.write = originalStderrWrite;
+      console.log = originalConsoleLog;
+      console.info = originalConsoleInfo;
+      console.warn = originalConsoleWarn;
+      console.error = originalConsoleError;
+
+      // Clear the UI
+      if (previousLineCount > 0) {
+        originalStdoutWrite.call(
+          process.stdout,
+          ansi.cursorUp(previousLineCount) + ansi.eraseDown,
+        );
+      }
+
+      process.stdout.removeListener("resize", resizeListener);
+    };
+  } else {
+    shutdown = () => {
+      // Restore original write methods
+      process.stdout.write = originalStdoutWrite;
+      process.stderr.write = originalStderrWrite;
+
+      // Clear the UI
+      if (previousLineCount > 0) {
+        originalStdoutWrite.call(
+          process.stdout,
+          ansi.cursorUp(previousLineCount) + ansi.eraseDown,
+        );
+      }
+
+      // Remove resize listener
+      process.stdout.removeListener("resize", resizeListener);
+    };
+  }
+
+  return {
+    refresh: () => {
+      const lines = getLines();
+      clearAndWriteLines(lines);
+    },
+    shutdown,
+  };
+}
+
+// Regex to strip ANSI escape sequences from a string
+const ansiEscapeRegex = new RegExp(
+  [
+    "[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)",
+    "(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))",
+  ].join("|"),
+  "g",
+);

package/src/utils/abi.ts

@@ -0,0 +1,103 @@
+import { getDuplicateElements } from "@/utils/duplicates.js";
+import {
+  type Abi,
+  type AbiEvent,
+  type AbiFunction,
+  formatAbiItem,
+} from "abitype";
+import {
+  type GetEventArgs,
+  type Hex,
+  encodeEventTopics,
+  getAbiItem,
+  parseAbiItem,
+} from "viem";
+import type { Config } from "../config/index.js";
+
+/**
+ * Fix issue with Array.isArray not checking readonly arrays
+ * {@link https://github.com/microsoft/TypeScript/issues/17002}
+ */
+declare global {
+  interface ArrayConstructor {
+    isArray(arg: ReadonlyArray<any> | any): arg is ReadonlyArray<any>;
+  }
+}
+
+export const toSafeName = ({
+  abi,
+  item,
+}: { abi: Abi; item: AbiEvent | AbiFunction }) => {
+  if (item.type === "event") {
+    const abiEvents = abi
+      .filter((item): item is AbiEvent => item.type === "event")
+      .filter(
+        (item) => item.anonymous === undefined || item.anonymous === false,
+      );
+
+    const overloadedEventNames = getDuplicateElements(
+      abiEvents.map((item) => item.name),
+    );
+
+    if (overloadedEventNames.has(item.name)) {
+      return formatAbiItem(item).split("event ")[1]!;
+    }
+    return item.name;
+  } else {
+    const abiFunctions = abi.filter(
+      (item): item is AbiFunction => item.type === "function",
+    );
+
+    const overloadedFunctionNames = getDuplicateElements(
+      abiFunctions.map((item) => item.name),
+    );
+
+    if (overloadedFunctionNames.has(item.name)) {
+      return formatAbiItem(item).split("function ")[1]!;
+    }
+    return `${item.name}()`;
+  }
+};
+
+export function buildTopics(
+  abi: Abi,
+  filter: NonNullable<Config["contracts"][string]["filter"]>,
+): {
+  topic0: Hex;
+  topic1: Hex | Hex[] | null;
+  topic2: Hex | Hex[] | null;
+  topic3: Hex | Hex[] | null;
+}[] {
+  const filters = Array.isArray(filter) ? filter : [filter];
+
+  const topics = filters.map((filter) => {
+    // Single event with args
+    const topics = encodeEventTopics({
+      abi: [findAbiEvent(abi, filter.event)],
+      args: filter.args as GetEventArgs<Abi, string>,
+    });
+
+    return {
+      topic0: topics[0],
+      topic1: topics[1] ?? null,
+      topic2: topics[2] ?? null,
+      topic3: topics[3] ?? null,
+    };
+  });
+
+  return topics;
+}
+
+/**
+ * Finds the event ABI item for the event name or event signature.
+ *
+ * @param eventName Event name or event signature if there are duplicates
+ */
+const findAbiEvent = (abi: Abi, eventName: string): AbiEvent => {
+  if (eventName.includes("(")) {
+    // full event signature
+    return parseAbiItem(`event ${eventName}`) as AbiEvent;
+  } else {
+    return getAbiItem({ abi, name: eventName }) as AbiEvent;
+  }
+};

package/src/utils/bigint.ts

@@ -0,0 +1,41 @@
+/**
+ * Returns the minimum BigInt value from an array of BigInts.
+ *
+ * @param {bigint[]} values - An array of BigInt values.
+ * @returns {bigint} The minimum BigInt value from the array.
+ */
+export function bigIntMin(values: bigint[]): bigint {
+  if (values.length === 0) {
+    throw new Error("Input array must not be empty.");
+  }
+
+  let minVal: bigint = values[0]!;
+  for (let i = 1; i < values.length; i++) {
+    if (values[i]! < minVal) {
+      minVal = values[i]!;
+    }
+  }
+
+  return minVal;
+}
+
+/**
+ * Returns the maximum BigInt value from an array of BigInts.
+ *
+ * @param {bigint[]} values - An array of BigInt values.
+ * @returns {bigint} The maximum BigInt value from the array.
+ */
+export function bigIntMax(values: bigint[]): bigint {
+  if (values.length === 0) {
+    throw new Error("Input array must not be empty.");
+  }
+
+  let maxVal: bigint = values[0]!;
+  for (let i = 1; i < values.length; i++) {
+    if (values[i]! > maxVal) {
+      maxVal = values[i]!;
+    }
+  }
+
+  return maxVal;
+}

package/src/utils/chains.ts

@@ -0,0 +1,22 @@
+import * as _chains from "viem/chains";
+import { defineChain } from "viem/utils";
+
+export const chains = _chains as unknown as Record<string, _chains.Chain>;
+
+// Note: wanchain testnet uses the same id as hyperliquid evm
+export const hyperliquidEvm = defineChain({
+  id: 999,
+  name: "Hyperliquid EVM",
+  nativeCurrency: { name: "HYPE", symbol: "HYPE", decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: ["https://rpc.hyperliquid.xyz/evm"],
+    },
+  },
+  contracts: {
+    multicall3: {
+      address: "0xca11bde05977b3631167028862be2a173976ca11",
+      blockCreated: 13051,
+    },
+  },
+});