@livo-build/runtime 0.2.0 → 0.2.2

package/dist/watch.d.ts

@@ -0,0 +1,44 @@
+import type { Chain } from "./chain.js";
+import type { Store } from "./store.js";
+import type { AbiEvent, DecodedLog } from "./events.js";
+import type { Hex } from "./hex.js";
+export interface WatchLogsOptions {
+    /** Event to decode — an AbiEvent or a human-readable signature. */
+    event: AbiEvent | string;
+    /** Contract address(es) to filter (omit to match any). */
+    address?: Hex | Hex[];
+    /** Indexed-arg filter, positional or by name (see Chain.getLogs). */
+    args?: Record<string, unknown> | unknown[];
+    /** Store key holding this watcher's cursor. Namespace it per watcher. */
+    cursorKey: string;
+    /** First block to scan when no cursor exists yet. Default: current head (new logs only). */
+    fromBlock?: bigint;
+    /** Stay this many blocks behind head for reorg safety. Default 0. */
+    confirmations?: bigint;
+    /** Max blocks per eth_getLogs window (RPC range cap). Default 2000n. */
+    chunkSize?: bigint;
+    /** Invoked per non-empty chunk with that chunk's decoded logs. Must be idempotent. */
+    onLogs: (logs: DecodedLog[], range: {
+        fromBlock: bigint;
+        toBlock: bigint;
+    }) => Promise<void> | void;
+}
+export interface WatchLogsResult {
+    /** First block scanned this run. */
+    fromBlock: bigint;
+    /** New cursor — the last block scanned (head - confirmations). */
+    toBlock: bigint;
+    /** Total logs delivered to onLogs this run. */
+    logCount: number;
+    /** Number of eth_getLogs windows scanned. */
+    chunks: number;
+}
+/**
+ * Catch up on event logs since the last run. Reads the cursor (or `fromBlock`),
+ * scans `[cursor, head - confirmations]` in `chunkSize` windows, calls `onLogs`
+ * per non-empty chunk, and persists the cursor AFTER each chunk — so a Worker
+ * killed mid-catch-up resumes from the last completed window. Delivery is
+ * at-least-once: if `onLogs` throws, the cursor is not advanced past that chunk
+ * and the next tick retries it, so `onLogs` must be idempotent.
+ */
+export declare function watchLogs(chain: Chain, store: Store, opts: WatchLogsOptions): Promise<WatchLogsResult>;

package/dist/watch.js

@@ -0,0 +1,46 @@
+// watchLogs — resumable event catch-up for keepers. A Worker has no long-lived
+// process, so this is NOT a websocket subscription: each scheduled tick reads new
+// logs since a Store-persisted block cursor, up to the (confirmed) head, in
+// chunked eth_getLogs windows. Layered as a free function over Chain + Store so
+// Chain (Layer 1, may hold keys) never imports Store (Layer 3).
+/**
+ * Catch up on event logs since the last run. Reads the cursor (or `fromBlock`),
+ * scans `[cursor, head - confirmations]` in `chunkSize` windows, calls `onLogs`
+ * per non-empty chunk, and persists the cursor AFTER each chunk — so a Worker
+ * killed mid-catch-up resumes from the last completed window. Delivery is
+ * at-least-once: if `onLogs` throws, the cursor is not advanced past that chunk
+ * and the next tick retries it, so `onLogs` must be idempotent.
+ */
+export async function watchLogs(chain, store, opts) {
+    const confirmations = opts.confirmations ?? 0n;
+    const chunkSize = opts.chunkSize ?? 2000n;
+    const head = await chain.getBlockNumber();
+    const safeHead = head - confirmations;
+    const stored = await store.getJSON(opts.cursorKey);
+    const from = stored ? BigInt(stored.next) : (opts.fromBlock ?? safeHead);
+    if (from > safeHead) {
+        return { fromBlock: from, toBlock: from - 1n, logCount: 0, chunks: 0 };
+    }
+    let cur = from;
+    let logCount = 0;
+    let chunks = 0;
+    while (cur <= safeHead) {
+        const to = cur + chunkSize - 1n < safeHead ? cur + chunkSize - 1n : safeHead;
+        const logs = await chain.getLogs({
+            event: opts.event,
+            address: opts.address,
+            args: opts.args,
+            fromBlock: cur,
+            toBlock: to,
+        });
+        chunks++;
+        if (logs.length) {
+            await opts.onLogs(logs, { fromBlock: cur, toBlock: to });
+            logCount += logs.length;
+        }
+        // Advance + persist only after a successful onLogs, so a throw retries this window.
+        await store.setJSON(opts.cursorKey, { next: (to + 1n).toString() });
+        cur = to + 1n;
+    }
+    return { fromBlock: from, toBlock: safeHead, logCount, chunks };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livo-build/runtime",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Livo runtime — chain signing/reads, D1 state, and logging for keepers, servers, and bots.",
   "type": "module",
   "license": "UNLICENSED",