@gzeoneth/gov-tracker 0.1.0

package/dist/utils/log-search.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Chunked log search with early exit optimization
+ *
+ * Critical performance pattern: 10-40x faster than naive log search
+ */
+import { ethers } from "ethers";
+/**
+ * Log filter parameters
+ */
+export interface LogFilter {
+    address?: string | string[];
+    topics?: (string | string[] | null)[];
+    fromBlock: number;
+    toBlock: number;
+}
+/**
+ * Search result with metadata
+ */
+export interface LogSearchResult {
+    logs: ethers.providers.Log[];
+    searchedBlocks: number;
+    chunksProcessed: number;
+    earlyExit: boolean;
+    /** The log that triggered early exit (if earlyExitCheck returned one) */
+    matchedLog?: ethers.providers.Log;
+}
+/**
+ * Options for log search
+ */
+export interface LogSearchOptions {
+    chunkSize?: number;
+    delayBetweenChunks?: number;
+    earlyExitCheck?: (logs: ethers.providers.Log[]) => ethers.providers.Log | undefined;
+    maxChunks?: number;
+    reverseDirection?: boolean;
+}
+/**
+ * Search for logs in chunks with early exit optimization
+ *
+ * @example
+ * ```typescript
+ * // Search for CallExecuted events, stop when found
+ * const result = await searchLogsInChunks(
+ *   l2Provider,
+ *   {
+ *     address: timelockAddress,
+ *     topics: [EVENT_TOPICS.CALL_EXECUTED, operationId],
+ *     fromBlock: queueBlock,
+ *     toBlock: currentBlock
+ *   },
+ *   {
+ *     chunkSize: 10_000_000,
+ *     earlyExitCheck: (logs) => logs.find(l => l.topics[1] === operationId) ?? null
+ *   }
+ * );
+ * ```
+ */
+export declare function searchLogsInChunks(provider: ethers.providers.Provider, filter: LogFilter, options?: LogSearchOptions): Promise<LogSearchResult>;
+/**
+ * Search for a single log matching a predicate
+ * Returns immediately when found (early exit optimization)
+ */
+export declare function findLog(provider: ethers.providers.Provider, filter: LogFilter, predicate: (log: ethers.providers.Log) => boolean, options?: Omit<LogSearchOptions, "earlyExitCheck">): Promise<ethers.providers.Log | undefined>;
+/**
+ * Generic find and parse event - consolidates the common pattern:
+ * getSearchDefaults → findLog → parse → null check
+ *
+ * Reduces boilerplate in timelock-discovery.ts and similar modules.
+ */
+export declare function findAndParseEvent<T>(provider: ethers.providers.Provider, filter: LogFilter, predicate: (log: ethers.providers.Log) => boolean, parser: (log: ethers.providers.Log) => T | null, options?: Omit<LogSearchOptions, "earlyExitCheck">): Promise<T | null>;
+/**
+ * Create a predicate that matches operationId in topics[1]
+ * Common pattern for timelock event filtering
+ */
+export declare function createOperationIdPredicate(operationId: string, addressEquals: (a: string, b: string) => boolean): (log: ethers.providers.Log) => boolean;
+//# sourceMappingURL=log-search.d.ts.map

package/dist/utils/log-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-search.d.ts","sourceRoot":"","sources":["../../src/utils/log-search.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAOhC;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK,MAAM,CAAC,SAAS,CAAC,GAAG,GAAG,SAAS,CAAC;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACnC,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAoH1B;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACnC,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,SAAS,CAAC,GAAG,KAAK,OAAO,EACjD,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,gBAAgB,CAAM,GACrD,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,GAAG,SAAS,CAAC,CAQ3C;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACnC,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,SAAS,CAAC,GAAG,KAAK,OAAO,EACjD,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,GAAG,IAAI,EAC/C,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,gBAAgB,CAAM,GACrD,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAInB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,GAC/C,CAAC,GAAG,EAAE,MAAM,CAAC,SAAS,CAAC,GAAG,KAAK,OAAO,CAExC"}

package/dist/utils/log-search.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * Chunked log search with early exit optimization
+ *
+ * Critical performance pattern: 10-40x faster than naive log search
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchLogsInChunks = searchLogsInChunks;
+exports.findLog = findLog;
+exports.findAndParseEvent = findAndParseEvent;
+exports.createOperationIdPredicate = createOperationIdPredicate;
+const constants_1 = require("../constants");
+const rpc_utils_1 = require("./rpc-utils");
+const logger_1 = require("./logger");
+const log = logger_1.loggers.rpc;
+/**
+ * Search for logs in chunks with early exit optimization
+ *
+ * @example
+ * ```typescript
+ * // Search for CallExecuted events, stop when found
+ * const result = await searchLogsInChunks(
+ *   l2Provider,
+ *   {
+ *     address: timelockAddress,
+ *     topics: [EVENT_TOPICS.CALL_EXECUTED, operationId],
+ *     fromBlock: queueBlock,
+ *     toBlock: currentBlock
+ *   },
+ *   {
+ *     chunkSize: 10_000_000,
+ *     earlyExitCheck: (logs) => logs.find(l => l.topics[1] === operationId) ?? null
+ *   }
+ * );
+ * ```
+ */
+async function searchLogsInChunks(provider, filter, options = {}) {
+    const { chunkSize = constants_1.DEFAULT_CHUNKING_CONFIG.l2ChunkSize, delayBetweenChunks = constants_1.DEFAULT_CHUNKING_CONFIG.delayBetweenChunks, earlyExitCheck, maxChunks, reverseDirection = false, } = options;
+    const allLogs = [];
+    let chunksProcessed = 0;
+    let earlyExit = false;
+    let matchedLog;
+    const { fromBlock, toBlock } = filter;
+    const totalBlocks = toBlock - fromBlock + 1;
+    const searchStart = Date.now();
+    const addressStr = Array.isArray(filter.address)
+        ? `[${filter.address.length} addrs]`
+        : filter.address;
+    log("searchLogsInChunks: %s blocks=%d-%d (%d blocks, ~%d chunks)", addressStr, fromBlock, toBlock, totalBlocks, Math.ceil(totalBlocks / chunkSize));
+    if (totalBlocks <= 0) {
+        return { logs: [], searchedBlocks: 0, chunksProcessed: 0, earlyExit: false };
+    }
+    // Generate chunk ranges
+    const chunks = [];
+    if (reverseDirection) {
+        // Search backwards (useful for finding most recent events)
+        for (let end = toBlock; end >= fromBlock; end -= chunkSize) {
+            const start = Math.max(end - chunkSize + 1, fromBlock);
+            chunks.push({ start, end });
+        }
+    }
+    else {
+        // Search forwards (default)
+        for (let start = fromBlock; start <= toBlock; start += chunkSize) {
+            const end = Math.min(start + chunkSize - 1, toBlock);
+            chunks.push({ start, end });
+        }
+    }
+    // Process chunks and track actual blocks searched
+    let actualBlocksSearched = 0;
+    for (const { start, end } of chunks) {
+        if (maxChunks && chunksProcessed >= maxChunks) {
+            break;
+        }
+        const chunkStart = Date.now();
+        const logs = await (0, rpc_utils_1.queryWithRetry)(() => provider.getLogs({
+            address: filter.address,
+            topics: filter.topics,
+            fromBlock: start,
+            toBlock: end,
+        }));
+        const chunkMs = Date.now() - chunkStart;
+        log("  chunk %d: blocks=%d-%d found=%d logs (%dms)", chunksProcessed + 1, start, end, logs.length, chunkMs);
+        allLogs.push(...logs);
+        chunksProcessed++;
+        actualBlocksSearched += end - start + 1;
+        // Early exit check - critical optimization
+        if (earlyExitCheck && logs.length > 0) {
+            const match = earlyExitCheck(logs);
+            if (match) {
+                earlyExit = true;
+                matchedLog = match;
+                break;
+            }
+        }
+        // Rate limiting between chunks
+        if (end < toBlock && delayBetweenChunks > 0) {
+            await (0, rpc_utils_1.delay)(delayBetweenChunks);
+        }
+    }
+    const totalMs = Date.now() - searchStart;
+    log("searchLogsInChunks done: %d logs, %d chunks, %dms%s", allLogs.length, chunksProcessed, totalMs, earlyExit ? " (early exit)" : "");
+    return {
+        logs: allLogs,
+        searchedBlocks: actualBlocksSearched,
+        chunksProcessed,
+        earlyExit,
+        matchedLog,
+    };
+}
+/**
+ * Search for a single log matching a predicate
+ * Returns immediately when found (early exit optimization)
+ */
+async function findLog(provider, filter, predicate, options = {}) {
+    const result = await searchLogsInChunks(provider, filter, {
+        ...options,
+        earlyExitCheck: (logs) => logs.find(predicate),
+    });
+    // Use matchedLog from early exit to avoid double-searching
+    return result.matchedLog;
+}
+/**
+ * Generic find and parse event - consolidates the common pattern:
+ * getSearchDefaults → findLog → parse → null check
+ *
+ * Reduces boilerplate in timelock-discovery.ts and similar modules.
+ */
+async function findAndParseEvent(provider, filter, predicate, parser, options = {}) {
+    const log = await findLog(provider, filter, predicate, options);
+    if (!log)
+        return null;
+    return parser(log);
+}
+/**
+ * Create a predicate that matches operationId in topics[1]
+ * Common pattern for timelock event filtering
+ */
+function createOperationIdPredicate(operationId, addressEquals) {
+    return (log) => (log.topics[1] ? addressEquals(log.topics[1], operationId) : false);
+}
+//# sourceMappingURL=log-search.js.map

package/dist/utils/log-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-search.js","sourceRoot":"","sources":["../../src/utils/log-search.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AA+DH,gDAwHC;AAMD,0BAaC;AAQD,8CAUC;AAMD,gEAKC;AApOD,4CAAuD;AACvD,2CAAoD;AACpD,qCAAmC;AAEnC,MAAM,GAAG,GAAG,gBAAO,CAAC,GAAG,CAAC;AAmCxB;;;;;;;;;;;;;;;;;;;;GAoBG;AACI,KAAK,UAAU,kBAAkB,CACtC,QAAmC,EACnC,MAAiB,EACjB,UAA4B,EAAE;IAE9B,MAAM,EACJ,SAAS,GAAG,mCAAuB,CAAC,WAAW,EAC/C,kBAAkB,GAAG,mCAAuB,CAAC,kBAAkB,EAC/D,cAAc,EACd,SAAS,EACT,gBAAgB,GAAG,KAAK,GACzB,GAAG,OAAO,CAAC;IAEZ,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,UAA4C,CAAC;IAEjD,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IACtC,MAAM,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE/B,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;QAC9C,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,SAAS;QACpC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;IACnB,GAAG,CACD,6DAA6D,EAC7D,UAAU,EACV,SAAS,EACT,OAAO,EACP,WAAW,EACX,IAAI,CAAC,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC,CACnC,CAAC;IAEF,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC/E,CAAC;IAED,wBAAwB;IACxB,MAAM,MAAM,GAA0C,EAAE,CAAC;IAEzD,IAAI,gBAAgB,EAAE,CAAC;QACrB,2DAA2D;QAC3D,KAAK,IAAI,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,GAAG,IAAI,SAAS,EAAE,CAAC;YAC3D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,SAAS,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC;YACvD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;SAAM,CAAC;QACN,4BAA4B;QAC5B,KAAK,IAAI,KAAK,GAAG,SAAS,EAAE,KAAK,IAAI,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,CAAC;YACjE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,SAAS,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;YACrD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,kDAAkD;IAClD,IAAI,oBAAoB,GAAG,CAAC,CAAC;IAE7B,KAAK,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,MAAM,EAAE,CAAC;QACpC,IAAI,SAAS,IAAI,eAAe,IAAI,SAAS,EAAE,CAAC;YAC9C,MAAM;QACR,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,MAAM,IAAA,0BAAc,EAAC,GAAG,EAAE,CACrC,QAAQ,CAAC,OAAO,CAAC;YACf,OAAO,EAAE,MAAM,CAAC,OAA6B;YAC7C,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,GAAG;SACb,CAAC,CACH,CAAC;QACF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,CAAC;QAExC,GAAG,CACD,+CAA+C,EAC/C,eAAe,GAAG,CAAC,EACnB,KAAK,EACL,GAAG,EACH,IAAI,CAAC,MAAM,EACX,OAAO,CACR,CAAC;QAEF,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACtB,eAAe,EAAE,CAAC;QAClB,oBAAoB,IAAI,GAAG,GAAG,KAAK,GAAG,CAAC,CAAC;QAExC,2CAA2C;QAC3C,IAAI,cAAc,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtC,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,KAAK,EAAE,CAAC;gBACV,SAAS,GAAG,IAAI,CAAC;gBACjB,UAAU,GAAG,KAAK,CAAC;gBACnB,MAAM;YACR,CAAC;QACH,CAAC;QAED,+BAA+B;QAC/B,IAAI,GAAG,GAAG,OAAO,IAAI,kBAAkB,GAAG,CAAC,EAAE,CAAC;YAC5C,MAAM,IAAA,iBAAK,EAAC,kBAAkB,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW,CAAC;IAEzC,GAAG,CACD,qDAAqD,EACrD,OAAO,CAAC,MAAM,EACd,eAAe,EACf,OAAO,EACP,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CACjC,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,OAAO;QACb,cAAc,EAAE,oBAAoB;QACpC,eAAe;QACf,SAAS;QACT,UAAU;KACX,CAAC;AACJ,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,OAAO,CAC3B,QAAmC,EACnC,MAAiB,EACjB,SAAiD,EACjD,UAAoD,EAAE;IAEtD,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE;QACxD,GAAG,OAAO;QACV,cAAc,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;KAC/C,CAAC,CAAC;IAEH,2DAA2D;IAC3D,OAAO,MAAM,CAAC,UAAU,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,iBAAiB,CACrC,QAAmC,EACnC,MAAiB,EACjB,SAAiD,EACjD,MAA+C,EAC/C,UAAoD,EAAE;IAEtD,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAChE,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,SAAgB,0BAA0B,CACxC,WAAmB,EACnB,aAAgD;IAEhD,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACtF,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Centralized debug loggers for the SDK
+ *
+ * Two types of loggers:
+ * 1. Regular loggers - for code that runs sequentially
+ * 2. Scoped loggers - for code that runs concurrently (auto-prefix with scope)
+ *
+ * Usage:
+ *   import { loggers } from "../utils/logger";
+ *   import { withScope } from "../utils/scoped-logger";
+ *
+ *   // Regular logging
+ *   loggers.tracker("message %s", value);
+ *
+ *   // Scoped logging (for concurrent operations)
+ *   await withScope("core-gov", async () => {
+ *     loggers.discovery("discovering..."); // [core-gov] discovering...
+ *   });
+ */
+export { withScope, getCurrentScope, scopedLog } from "./scoped-logger";
+/**
+ * Pre-configured debug loggers for common namespaces.
+ *
+ * Scoped loggers (discovery, pipeline, stage.*) automatically include
+ * the current scope prefix when used within withScope().
+ */
+export declare const loggers: {
+    readonly tracker: (fmt: string, ...args: unknown[]) => void;
+    readonly execution: (fmt: string, ...args: unknown[]) => void;
+    readonly election: (fmt: string, ...args: unknown[]) => void;
+    readonly rpc: (fmt: string, ...args: unknown[]) => void;
+    readonly retryables: (fmt: string, ...args: unknown[]) => void;
+    readonly discovery: (fmt: string, ...args: unknown[]) => void;
+    readonly pipeline: (fmt: string, ...args: unknown[]) => void;
+    readonly stage: {
+        readonly timelock: (fmt: string, ...args: unknown[]) => void;
+        readonly l2ToL1: (fmt: string, ...args: unknown[]) => void;
+        readonly proposalQueued: (fmt: string, ...args: unknown[]) => void;
+    };
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;CAcV,CAAC"}

package/dist/utils/logger.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Centralized debug loggers for the SDK
+ *
+ * Two types of loggers:
+ * 1. Regular loggers - for code that runs sequentially
+ * 2. Scoped loggers - for code that runs concurrently (auto-prefix with scope)
+ *
+ * Usage:
+ *   import { loggers } from "../utils/logger";
+ *   import { withScope } from "../utils/scoped-logger";
+ *
+ *   // Regular logging
+ *   loggers.tracker("message %s", value);
+ *
+ *   // Scoped logging (for concurrent operations)
+ *   await withScope("core-gov", async () => {
+ *     loggers.discovery("discovering..."); // [core-gov] discovering...
+ *   });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loggers = exports.scopedLog = exports.getCurrentScope = exports.withScope = void 0;
+const scoped_logger_1 = require("./scoped-logger");
+// Re-export scoped logging utilities
+var scoped_logger_2 = require("./scoped-logger");
+Object.defineProperty(exports, "withScope", { enumerable: true, get: function () { return scoped_logger_2.withScope; } });
+Object.defineProperty(exports, "getCurrentScope", { enumerable: true, get: function () { return scoped_logger_2.getCurrentScope; } });
+Object.defineProperty(exports, "scopedLog", { enumerable: true, get: function () { return scoped_logger_2.scopedLog; } });
+/**
+ * Pre-configured debug loggers for common namespaces.
+ *
+ * Scoped loggers (discovery, pipeline, stage.*) automatically include
+ * the current scope prefix when used within withScope().
+ */
+exports.loggers = {
+    // Scoped loggers - auto-prefix with current scope (tracker ID, governor name, etc.)
+    tracker: (0, scoped_logger_1.scopedLog)("gov-tracker:tracker"),
+    execution: (0, scoped_logger_1.scopedLog)("gov-tracker:execution"),
+    election: (0, scoped_logger_1.scopedLog)("gov-tracker:election"),
+    rpc: (0, scoped_logger_1.scopedLog)("gov-tracker:rpc"),
+    retryables: (0, scoped_logger_1.scopedLog)("gov-tracker:retryables"),
+    discovery: (0, scoped_logger_1.scopedLog)("gov-tracker:discovery"),
+    pipeline: (0, scoped_logger_1.scopedLog)("gov-tracker:pipeline"),
+    stage: {
+        timelock: (0, scoped_logger_1.scopedLog)("gov-tracker:stage:timelock"),
+        l2ToL1: (0, scoped_logger_1.scopedLog)("gov-tracker:stage:l2-to-l1-message"),
+        proposalQueued: (0, scoped_logger_1.scopedLog)("gov-tracker:stage:proposal-queued"),
+    },
+};
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAEH,mDAA4C;AAE5C,qCAAqC;AACrC,iDAAwE;AAA/D,0GAAA,SAAS,OAAA;AAAE,gHAAA,eAAe,OAAA;AAAE,0GAAA,SAAS,OAAA;AAE9C;;;;;GAKG;AACU,QAAA,OAAO,GAAG;IACrB,oFAAoF;IACpF,OAAO,EAAE,IAAA,yBAAS,EAAC,qBAAqB,CAAC;IACzC,SAAS,EAAE,IAAA,yBAAS,EAAC,uBAAuB,CAAC;IAC7C,QAAQ,EAAE,IAAA,yBAAS,EAAC,sBAAsB,CAAC;IAC3C,GAAG,EAAE,IAAA,yBAAS,EAAC,iBAAiB,CAAC;IACjC,UAAU,EAAE,IAAA,yBAAS,EAAC,wBAAwB,CAAC;IAC/C,SAAS,EAAE,IAAA,yBAAS,EAAC,uBAAuB,CAAC;IAC7C,QAAQ,EAAE,IAAA,yBAAS,EAAC,sBAAsB,CAAC;IAC3C,KAAK,EAAE;QACL,QAAQ,EAAE,IAAA,yBAAS,EAAC,4BAA4B,CAAC;QACjD,MAAM,EAAE,IAAA,yBAAS,EAAC,oCAAoC,CAAC;QACvD,cAAc,EAAE,IAAA,yBAAS,EAAC,mCAAmC,CAAC;KAC/D;CACO,CAAC"}

package/dist/utils/operation-id.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Operation ID utilities
+ *
+ * Uses on-chain timelock contract calls for operation ID computation
+ * to ensure consistency with the actual contract behavior.
+ */
+import { ethers } from "ethers";
+import { TimelockBatchParams, TimelockParams } from "../types";
+/**
+ * Compute operation ID using on-chain timelock contract
+ */
+export declare function hashOperation(timelockAddress: string, params: TimelockParams, provider: ethers.providers.Provider): Promise<string>;
+/**
+ * Compute batch operation ID using on-chain timelock contract
+ */
+export declare function hashOperationBatch(timelockAddress: string, params: TimelockBatchParams, provider: ethers.providers.Provider): Promise<string>;
+/**
+ * Validate that a salt produces the expected operation ID
+ */
+export declare function validateSalt(timelockAddress: string, expectedOperationId: string, params: TimelockParams, provider: ethers.providers.Provider): Promise<boolean>;
+/**
+ * Validate that a salt produces the expected operation ID for a batch
+ */
+export declare function validateSaltBatch(timelockAddress: string, expectedOperationId: string, params: TimelockBatchParams, provider: ethers.providers.Provider): Promise<boolean>;
+/**
+ * Try salt candidates to find matching salt for an operation
+ *
+ * Supports both single and batch operations.
+ */
+export declare function tryFindSalt(timelockAddress: string, expectedOperationId: string, baseParams: Omit<TimelockParams, "salt"> | Omit<TimelockBatchParams, "salt">, candidates: string[], provider: ethers.providers.Provider): Promise<string | null>;
+/**
+ * Validate operation parameters and return computed hash with validation status.
+ *
+ * This is useful for debugging when you want to see the computed hash
+ * and whether it matches the expected operation ID.
+ *
+ * @param timelockAddress - Address of the timelock contract
+ * @param expectedOperationId - Expected operation ID to validate against
+ * @param params - Operation parameters (single or batch)
+ * @param provider - Provider for RPC calls
+ * @returns Computed hash and whether it matches expected
+ */
+export declare function computeAndValidateOperationHash(timelockAddress: string, expectedOperationId: string, params: TimelockParams | TimelockBatchParams, provider: ethers.providers.Provider): Promise<{
+    computedHash: string;
+    isValid: boolean;
+    error?: string;
+}>;
+//# sourceMappingURL=operation-id.d.ts.map

package/dist/utils/operation-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-id.d.ts","sourceRoot":"","sources":["../../src/utils/operation-id.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAK/D;;GAEG;AACH,wBAAsB,aAAa,CACjC,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GAClC,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,mBAAmB,EAC3B,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GAClC,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,eAAe,EAAE,MAAM,EACvB,mBAAmB,EAAE,MAAM,EAC3B,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GAClC,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,eAAe,EAAE,MAAM,EACvB,mBAAmB,EAAE,MAAM,EAC3B,MAAM,EAAE,mBAAmB,EAC3B,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GAClC,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,eAAe,EAAE,MAAM,EACvB,mBAAmB,EAAE,MAAM,EAC3B,UAAU,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAAC,EAC5E,UAAU,EAAE,MAAM,EAAE,EACpB,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GAClC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAuBxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,+BAA+B,CACnD,eAAe,EAAE,MAAM,EACvB,mBAAmB,EAAE,MAAM,EAC3B,MAAM,EAAE,cAAc,GAAG,mBAAmB,EAC5C,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GAClC,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAuBrE"}

package/dist/utils/operation-id.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Operation ID utilities
+ *
+ * Uses on-chain timelock contract calls for operation ID computation
+ * to ensure consistency with the actual contract behavior.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashOperation = hashOperation;
+exports.hashOperationBatch = hashOperationBatch;
+exports.validateSalt = validateSalt;
+exports.validateSaltBatch = validateSaltBatch;
+exports.tryFindSalt = tryFindSalt;
+exports.computeAndValidateOperationHash = computeAndValidateOperationHash;
+const ethers_1 = require("ethers");
+const rpc_utils_1 = require("./rpc-utils");
+const abis_1 = require("../abis");
+const chain_1 = require("./chain");
+/**
+ * Compute operation ID using on-chain timelock contract
+ */
+async function hashOperation(timelockAddress, params, provider) {
+    const timelock = new ethers_1.ethers.Contract(timelockAddress, abis_1.TIMELOCK_ABI, provider);
+    const { target, value, data, predecessor, salt } = params;
+    return (0, rpc_utils_1.queryWithRetry)(() => timelock.hashOperation(target, value, data, predecessor, salt));
+}
+/**
+ * Compute batch operation ID using on-chain timelock contract
+ */
+async function hashOperationBatch(timelockAddress, params, provider) {
+    const timelock = new ethers_1.ethers.Contract(timelockAddress, abis_1.TIMELOCK_ABI, provider);
+    const { targets, values, payloads, predecessor, salt } = params;
+    return (0, rpc_utils_1.queryWithRetry)(() => timelock.hashOperationBatch(targets, values, payloads, predecessor, salt));
+}
+/**
+ * Validate that a salt produces the expected operation ID
+ */
+async function validateSalt(timelockAddress, expectedOperationId, params, provider) {
+    const computed = await hashOperation(timelockAddress, params, provider);
+    return (0, chain_1.addressEquals)(computed, expectedOperationId);
+}
+/**
+ * Validate that a salt produces the expected operation ID for a batch
+ */
+async function validateSaltBatch(timelockAddress, expectedOperationId, params, provider) {
+    const computed = await hashOperationBatch(timelockAddress, params, provider);
+    return (0, chain_1.addressEquals)(computed, expectedOperationId);
+}
+/**
+ * Try salt candidates to find matching salt for an operation
+ *
+ * Supports both single and batch operations.
+ */
+async function tryFindSalt(timelockAddress, expectedOperationId, baseParams, candidates, provider) {
+    const isBatch = "targets" in baseParams;
+    for (const salt of candidates) {
+        const fullParams = { ...baseParams, salt };
+        const isValid = isBatch
+            ? await validateSaltBatch(timelockAddress, expectedOperationId, fullParams, provider)
+            : await validateSalt(timelockAddress, expectedOperationId, fullParams, provider);
+        if (isValid) {
+            return salt;
+        }
+    }
+    return null;
+}
+/**
+ * Validate operation parameters and return computed hash with validation status.
+ *
+ * This is useful for debugging when you want to see the computed hash
+ * and whether it matches the expected operation ID.
+ *
+ * @param timelockAddress - Address of the timelock contract
+ * @param expectedOperationId - Expected operation ID to validate against
+ * @param params - Operation parameters (single or batch)
+ * @param provider - Provider for RPC calls
+ * @returns Computed hash and whether it matches expected
+ */
+async function computeAndValidateOperationHash(timelockAddress, expectedOperationId, params, provider) {
+    try {
+        const isBatch = "targets" in params;
+        const computed = isBatch
+            ? await hashOperationBatch(timelockAddress, params, provider)
+            : await hashOperation(timelockAddress, params, provider);
+        const isValid = (0, chain_1.addressEquals)(computed, expectedOperationId);
+        return {
+            computedHash: computed,
+            isValid,
+            error: isValid
+                ? undefined
+                : `Operation hash mismatch: computed ${computed} but expected ${expectedOperationId}. This may indicate incorrect salt or operation parameters.`,
+        };
+    }
+    catch (err) {
+        return {
+            computedHash: "",
+            isValid: false,
+            error: `Failed to compute operation hash: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+//# sourceMappingURL=operation-id.js.map

package/dist/utils/operation-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-id.js","sourceRoot":"","sources":["../../src/utils/operation-id.ts"],"names":[],"mappings":"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"}

package/dist/utils/rpc-utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * RPC utilities with retry logic and rate limiting
+ */
+import { RetryConfig } from "../types";
+/**
+ * Delay for specified milliseconds
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Error type for RPC failures
+ */
+export declare class RpcError extends Error {
+    readonly code?: string | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, code?: string | undefined, cause?: Error | undefined);
+}
+/**
+ * Check if an error is retryable
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Query with retry and exponential backoff
+ *
+ * @example
+ * ```typescript
+ * const result = await queryWithRetry(() => provider.getBlockNumber());
+ * ```
+ */
+export declare function queryWithRetry<T>(queryFn: () => Promise<T>, config?: RetryConfig): Promise<T>;
+//# sourceMappingURL=rpc-utils.d.ts.map

package/dist/utils/rpc-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-utils.d.ts","sourceRoot":"","sources":["../../src/utils/rpc-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAMvC;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAGf,IAAI,CAAC,EAAE,MAAM;aACb,KAAK,CAAC,EAAE,KAAK;gBAF7B,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,MAAM,YAAA,EACb,KAAK,CAAC,EAAE,KAAK,YAAA;CAKhC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAyCxD;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,MAAM,GAAE,WAAkC,GACzC,OAAO,CAAC,CAAC,CAAC,CAsCZ"}

package/dist/utils/rpc-utils.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * RPC utilities with retry logic and rate limiting
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RpcError = void 0;
+exports.delay = delay;
+exports.isRetryableError = isRetryableError;
+exports.queryWithRetry = queryWithRetry;
+const constants_1 = require("../constants");
+const logger_1 = require("./logger");
+const log = logger_1.loggers.rpc;
+/**
+ * Delay for specified milliseconds
+ */
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Error type for RPC failures
+ */
+class RpcError extends Error {
+    constructor(message, code, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = "RpcError";
+    }
+}
+exports.RpcError = RpcError;
+/**
+ * Check if an error is retryable
+ */
+function isRetryableError(error) {
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        // Rate limiting errors
+        if (message.includes("rate limit") ||
+            message.includes("too many requests") ||
+            message.includes("429")) {
+            return true;
+        }
+        // Server errors
+        if (message.includes("server error") ||
+            message.includes("502") ||
+            message.includes("503") ||
+            message.includes("504")) {
+            return true;
+        }
+        // Connection errors
+        if (message.includes("econnreset") ||
+            message.includes("econnrefused") ||
+            message.includes("etimedout") ||
+            message.includes("network error") ||
+            message.includes("timeout")) {
+            return true;
+        }
+        // Provider-specific errors
+        if (message.includes("missing response") || message.includes("request failed")) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Query with retry and exponential backoff
+ *
+ * @example
+ * ```typescript
+ * const result = await queryWithRetry(() => provider.getBlockNumber());
+ * ```
+ */
+async function queryWithRetry(queryFn, config = constants_1.DEFAULT_RETRY_CONFIG) {
+    let retryDelay = config.initialDelay;
+    let lastError;
+    for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+        try {
+            return await queryFn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Don't retry non-retryable errors
+            if (!isRetryableError(error)) {
+                const code = error?.code?.toString();
+                log("query failed (non-retryable): %s", lastError.message);
+                throw new RpcError(`RPC query failed: ${lastError.message}`, code, lastError);
+            }
+            // Don't retry on last attempt
+            if (attempt < config.maxRetries) {
+                log("retry attempt %d/%d after %dms: %s", attempt + 1, config.maxRetries, retryDelay, lastError.message);
+                await delay(retryDelay);
+                retryDelay = Math.min(retryDelay * config.backoffMultiplier, config.maxDelay);
+            }
+        }
+    }
+    log("all %d retries exhausted: %s", config.maxRetries + 1, lastError?.message);
+    throw new RpcError(`All ${config.maxRetries + 1} retry attempts failed: ${lastError?.message ?? "Unknown error"}`, undefined, lastError);
+}
+//# sourceMappingURL=rpc-utils.js.map

package/dist/utils/rpc-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-utils.js","sourceRoot":"","sources":["../../src/utils/rpc-utils.ts"],"names":[],"mappings":"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"}