@gzeoneth/gov-tracker 0.2.1-beta.ec7d8a7 → 0.2.1-beta.f5af747

package/dist/tracker/checkpoint-helpers.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Checkpoint Helper Utilities
+ *
+ * Shared functions for working with TrackingCheckpoint objects
+ * across proposals, timelocks, and elections.
+ */
+import type { TrackingCheckpoint, TrackerStats } from "../types";
+export declare const DEFAULT_ERROR_THRESHOLD = 5;
+/**
+ * Checkpoint metadata type (matches TrackingCheckpoint.metadata)
+ */
+export interface CheckpointMetadata {
+    errorCount: number;
+    lastTrackedAt: number;
+}
+/**
+ * Create standard checkpoint metadata
+ */
+export declare function createCheckpointMetadata(errorCount?: number): CheckpointMetadata;
+/**
+ * Increment error count for retry logic
+ * Gas errors don't increment the count (transient)
+ */
+export declare function incrementErrorCount(currentCount: number, error: Error | string): number;
+/**
+ * Check if checkpoint has too many errors to continue tracking
+ */
+export declare function isCheckpointErrored(checkpoint: TrackingCheckpoint, threshold?: number): boolean;
+/**
+ * Check if checkpoint represents a completed tracking
+ * Works for both proposal/timelock (completedStages) and election (phase) checkpoints
+ */
+export declare function isCheckpointComplete(checkpoint: TrackingCheckpoint): boolean;
+/**
+ * Get the error count from a checkpoint
+ */
+export declare function getCheckpointErrorCount(checkpoint: TrackingCheckpoint): number;
+/**
+ * Cache key format utilities
+ */
+export declare const ELECTION_KEY_PREFIX = "election:";
+export declare const TX_KEY_PREFIX = "tx:";
+export declare const DISCOVERY_KEY_PREFIX = "discovery:";
+export declare const WATERMARKS_KEY = "discovery:watermarks";
+export declare function electionCacheKey(electionIndex: number): string;
+export declare function txHashCacheKey(txHash: string): string;
+export declare function isElectionKey(key: string): boolean;
+export declare function isTxKey(key: string): boolean;
+export declare function isDiscoveryKey(key: string): boolean;
+/**
+ * Extract election index from cache key
+ */
+export declare function parseElectionKey(key: string): number | null;
+/**
+ * Compute aggregated stats from loaded checkpoints.
+ *
+ * This is the single source of truth for stats computation. Used by:
+ * - tracker/query.ts::getStats() (loads from cache adapter)
+ * - cli/lib/cli.ts (loads from file)
+ * - useCache.ts (already has loaded data)
+ */
+export declare function computeCacheStats(checkpoints: Map<string, TrackingCheckpoint>, elections: Map<number, TrackingCheckpoint>, maxErrorCount?: number): TrackerStats;
+//# sourceMappingURL=checkpoint-helpers.d.ts.map

package/dist/tracker/checkpoint-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-helpers.d.ts","sourceRoot":"","sources":["../../src/tracker/checkpoint-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAIjE,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,SAAI,GAAG,kBAAkB,CAK3E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CASvF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,kBAAkB,EAC9B,SAAS,SAA0B,GAClC,OAAO,CAGT;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAc5E;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,kBAAkB,GAAG,MAAM,CAE9E;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAC/C,eAAO,MAAM,aAAa,QAAQ,CAAC;AACnC,eAAO,MAAM,oBAAoB,eAAe,CAAC;AACjD,eAAO,MAAM,cAAc,yBAAyB,CAAC;AAErD,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE5C;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI3D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAC5C,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAC1C,aAAa,GAAE,MAAgC,GAC9C,YAAY,CAiEd"}

package/dist/tracker/checkpoint-helpers.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Checkpoint Helper Utilities
+ *
+ * Shared functions for working with TrackingCheckpoint objects
+ * across proposals, timelocks, and elections.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WATERMARKS_KEY = exports.DISCOVERY_KEY_PREFIX = exports.TX_KEY_PREFIX = exports.ELECTION_KEY_PREFIX = exports.DEFAULT_ERROR_THRESHOLD = void 0;
+exports.createCheckpointMetadata = createCheckpointMetadata;
+exports.incrementErrorCount = incrementErrorCount;
+exports.isCheckpointErrored = isCheckpointErrored;
+exports.isCheckpointComplete = isCheckpointComplete;
+exports.getCheckpointErrorCount = getCheckpointErrorCount;
+exports.electionCacheKey = electionCacheKey;
+exports.txHashCacheKey = txHashCacheKey;
+exports.isElectionKey = isElectionKey;
+exports.isTxKey = isTxKey;
+exports.isDiscoveryKey = isDiscoveryKey;
+exports.parseElectionKey = parseElectionKey;
+exports.computeCacheStats = computeCacheStats;
+const utils_1 = require("../stages/utils");
+const constants_1 = require("../constants");
+exports.DEFAULT_ERROR_THRESHOLD = 5;
+/**
+ * Create standard checkpoint metadata
+ */
+function createCheckpointMetadata(errorCount = 0) {
+    return {
+        errorCount,
+        lastTrackedAt: Date.now(),
+    };
+}
+/**
+ * Increment error count for retry logic
+ * Gas errors don't increment the count (transient)
+ */
+function incrementErrorCount(currentCount, error) {
+    const isGasError = error instanceof Error
+        ? error.message.includes("insufficient funds") ||
+            error.message.includes("gas required exceeds allowance")
+        : typeof error === "string" &&
+            (error.includes("insufficient funds") || error.includes("gas required exceeds allowance"));
+    return isGasError ? currentCount : currentCount + 1;
+}
+/**
+ * Check if checkpoint has too many errors to continue tracking
+ */
+function isCheckpointErrored(checkpoint, threshold = exports.DEFAULT_ERROR_THRESHOLD) {
+    const errorCount = checkpoint.metadata?.errorCount ?? 0;
+    return errorCount >= threshold;
+}
+/**
+ * Check if checkpoint represents a completed tracking
+ * Works for both proposal/timelock (completedStages) and election (phase) checkpoints
+ */
+function isCheckpointComplete(checkpoint) {
+    const inputType = checkpoint.input.type;
+    if (inputType === "election") {
+        const electionStatus = checkpoint.cachedData?.electionStatus;
+        return electionStatus?.phase === "COMPLETED";
+    }
+    if (inputType === "discovery") {
+        return false;
+    }
+    const stages = checkpoint.cachedData?.completedStages ?? [];
+    return stages.length > 0 && (0, utils_1.areAllStagesComplete)(stages);
+}
+/**
+ * Get the error count from a checkpoint
+ */
+function getCheckpointErrorCount(checkpoint) {
+    return checkpoint.metadata?.errorCount ?? 0;
+}
+/**
+ * Cache key format utilities
+ */
+exports.ELECTION_KEY_PREFIX = "election:";
+exports.TX_KEY_PREFIX = "tx:";
+exports.DISCOVERY_KEY_PREFIX = "discovery:";
+exports.WATERMARKS_KEY = "discovery:watermarks";
+function electionCacheKey(electionIndex) {
+    return `${exports.ELECTION_KEY_PREFIX}${electionIndex}`;
+}
+function txHashCacheKey(txHash) {
+    return `${exports.TX_KEY_PREFIX}${txHash.toLowerCase()}`;
+}
+function isElectionKey(key) {
+    return key.startsWith(exports.ELECTION_KEY_PREFIX);
+}
+function isTxKey(key) {
+    return key.startsWith(exports.TX_KEY_PREFIX);
+}
+function isDiscoveryKey(key) {
+    return key.startsWith(exports.DISCOVERY_KEY_PREFIX);
+}
+/**
+ * Extract election index from cache key
+ */
+function parseElectionKey(key) {
+    if (!isElectionKey(key))
+        return null;
+    const index = parseInt(key.slice(exports.ELECTION_KEY_PREFIX.length), 10);
+    return isNaN(index) ? null : index;
+}
+/**
+ * Compute aggregated stats from loaded checkpoints.
+ *
+ * This is the single source of truth for stats computation. Used by:
+ * - tracker/query.ts::getStats() (loads from cache adapter)
+ * - cli/lib/cli.ts (loads from file)
+ * - useCache.ts (already has loaded data)
+ */
+function computeCacheStats(checkpoints, elections, maxErrorCount = exports.DEFAULT_ERROR_THRESHOLD) {
+    let proposalTotal = 0, proposalComplete = 0, proposalActive = 0, proposalErrored = 0;
+    let timelockTotal = 0, timelockComplete = 0, timelockActive = 0, timelockErrored = 0;
+    let electionTotal = 0, electionComplete = 0;
+    for (const checkpoint of checkpoints.values()) {
+        const complete = isCheckpointComplete(checkpoint);
+        const errored = isCheckpointErrored(checkpoint, maxErrorCount);
+        const inputType = checkpoint.input.type;
+        if (inputType === "governor") {
+            if (checkpoint.input.governorAddress &&
+                (0, constants_1.isElectionGovernor)(checkpoint.input.governorAddress)) {
+                continue;
+            }
+            proposalTotal++;
+            if (complete)
+                proposalComplete++;
+            else if (errored)
+                proposalErrored++;
+            else
+                proposalActive++;
+        }
+        else if (inputType === "election") {
+            electionTotal++;
+            if (complete)
+                electionComplete++;
+        }
+        else if (inputType === "timelock") {
+            timelockTotal++;
+            if (complete)
+                timelockComplete++;
+            else if (errored)
+                timelockErrored++;
+            else
+                timelockActive++;
+        }
+    }
+    for (const checkpoint of elections.values()) {
+        electionTotal++;
+        if (isCheckpointComplete(checkpoint)) {
+            electionComplete++;
+        }
+    }
+    return {
+        total: checkpoints.size + elections.size,
+        proposals: {
+            total: proposalTotal,
+            complete: proposalComplete,
+            active: proposalActive,
+            errored: proposalErrored,
+        },
+        timelocks: {
+            total: timelockTotal,
+            complete: timelockComplete,
+            active: timelockActive,
+            errored: timelockErrored,
+        },
+        elections: {
+            total: electionTotal,
+            complete: electionComplete,
+        },
+    };
+}
+//# sourceMappingURL=checkpoint-helpers.js.map

package/dist/tracker/checkpoint-helpers.js.map

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

package/dist/tracker/discovery.d.ts

@@ -5,7 +5,7 @@
  * Provides unified discovery API with watermark management.
  */
 import { ethers } from "ethers";
-import { DiscoveryWatermarks, DiscoveryTargets, CacheAdapter } from "../types";
+import { DiscoveryWatermarks, WatermarkHashes, DiscoveryTargets, DiscoveryKey, CacheAdapter } from "../types";
 import { DiscoveredProposal } from "../discovery/governor-discovery";
 import { DiscoveredTimelockOp } from "../discovery/timelock-discovery";
 export { DiscoveredProposal, DiscoveredTimelockOp };
@@ -14,18 +14,44 @@ export { DiscoveredProposal, DiscoveredTimelockOp };
  * Uses "discovery:" prefix to follow checkpoint pattern.
  */
 export declare const WATERMARKS_KEY = "discovery:watermarks";
+/**
+ * Loaded watermark data including block hashes for reorg detection.
+ */
+export interface LoadedWatermarks {
+    watermarks: DiscoveryWatermarks;
+    hashes: WatermarkHashes;
+}
 /**
  * Load discovery watermarks from cache.
  * Watermarks are stored as a TrackingCheckpoint for unified cache format.
- * Returns empty object if no watermarks are cached.
+ * Returns empty objects if no watermarks are cached.
+ */
+export declare function loadWatermarks(cache: CacheAdapter | undefined): Promise<LoadedWatermarks>;
+/**
+ * Verify a watermark's block hash against the chain.
+ * If the hash doesn't match (reorg detected), returns a rolled-back block number.
+ *
+ * @param key - Watermark key for logging
+ * @param blockNumber - The watermark block number to verify
+ * @param expectedHash - The stored block hash (undefined if not stored)
+ * @param provider - Provider to fetch current block hash
+ * @returns The verified block number (original if valid, rolled back if reorg detected)
  */
-export declare function loadWatermarks(cache: CacheAdapter | undefined): Promise<DiscoveryWatermarks>;
+export declare function verifyWatermark(key: DiscoveryKey, blockNumber: number, expectedHash: string | undefined, provider: ethers.providers.Provider): Promise<{
+    blockNumber: number;
+    isValid: boolean;
+    newHash?: string;
+}>;
 /**
  * Save discovery watermarks to cache.
  * Watermarks are stored as TrackingCheckpoint with proper metadata,
  * following the same pattern as proposal/timelock checkpoints.
+ *
+ * @param watermarks - Block numbers per discovery key
+ * @param hashes - Block hashes per discovery key (for reorg detection)
+ * @param cache - Cache adapter
  */
-export declare function saveWatermarks(watermarks: DiscoveryWatermarks, cache: CacheAdapter | undefined): Promise<void>;
+export declare function saveWatermarks(watermarks: DiscoveryWatermarks, hashes: WatermarkHashes, cache: CacheAdapter | undefined): Promise<void>;
 /**
  * Discover proposals from a governor in a block range.
  *
@@ -61,29 +87,34 @@ export declare function discoverTimelockOps(timelockAddress: string, fromBlock:
  * 2. The monitor-loop skips timelock ops that were tracked via governor
  * 3. Creating pending checkpoints for all timelock ops causes double-counting
  */
-export declare function createPendingCheckpoints(proposals: DiscoveredProposal[], _timelockOps: DiscoveredTimelockOp[], cache: CacheAdapter | undefined): Promise<void>;
+export declare function createPendingCheckpoints(proposals: DiscoveredProposal[], timelockOps: DiscoveredTimelockOp[], cache: CacheAdapter | undefined): Promise<void>;
 /**
  * Discover all proposals and timelock operations with auto-watermark management.
  *
  * This is the unified discovery API that handles everything internally:
+ * - Verifies watermark hashes to detect chain reorgs (rolls back if mismatch)
  * - Loads watermarks from provided watermarks or starts from governance deployment
  * - Discovers from all enabled targets in parallel (with scoped logging)
  * - Creates pending checkpoints for discovered items
- * - Returns updated watermarks for saving
+ * - Returns updated watermarks and hashes for saving
  *
  * @param targets - Which governors/timelocks to scan
  * @param toBlock - End block for discovery
  * @param l2Provider - L2 provider
  * @param cache - Cache adapter for pending checkpoint creation
- * @param fromWatermarks - Starting watermarks
+ * @param fromWatermarks - Starting watermarks (block numbers)
+ * @param fromHashes - Starting hashes for reorg detection
  * @param options.chunkSize - Optional chunk size for log searches
- * @returns Discovered proposals, timelock ops, and updated watermarks
+ * @param options.skipReorgCheck - Skip reorg verification (for testing)
+ * @returns Discovered proposals, timelock ops, updated watermarks and hashes
  */
-export declare function discoverAll(targets: DiscoveryTargets, toBlock: number, l2Provider: ethers.providers.Provider, cache: CacheAdapter | undefined, fromWatermarks: DiscoveryWatermarks, options?: {
+export declare function discoverAll(targets: DiscoveryTargets, toBlock: number, l2Provider: ethers.providers.Provider, cache: CacheAdapter | undefined, fromWatermarks: DiscoveryWatermarks, fromHashes?: WatermarkHashes, options?: {
     chunkSize?: number;
+    skipReorgCheck?: boolean;
 }): Promise<{
     proposals: DiscoveredProposal[];
     timelockOps: DiscoveredTimelockOp[];
     watermarks: DiscoveryWatermarks;
+    hashes: WatermarkHashes;
 }>;
 //# sourceMappingURL=discovery.d.ts.map

package/dist/tracker/discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/tracker/discovery.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAsB,mBAAmB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEnG,OAAO,EAEL,kBAAkB,EACnB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAEL,oBAAoB,EACrB,MAAM,iCAAiC,CAAC;AAKzC,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,cAAc,yBAAyB,CAAC;AAErD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,YAAY,GAAG,SAAS,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CAI9B;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,mBAAmB,EAC/B,KAAK,EAAE,YAAY,GAAG,SAAS,GAC9B,OAAO,CAAC,IAAI,CAAC,CAgCf;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAG/B;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAGjC;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,kBAAkB,EAAE,EAC/B,YAAY,EAAE,oBAAoB,EAAE,EACpC,KAAK,EAAE,YAAY,GAAG,SAAS,GAC9B,OAAO,CAAC,IAAI,CAAC,CAiCf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,KAAK,EAAE,YAAY,GAAG,SAAS,EAC/B,cAAc,EAAE,mBAAmB,EACnC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,OAAO,CAAC;IACT,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,UAAU,EAAE,mBAAmB,CAAC;CACjC,CAAC,CA6HD"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/tracker/discovery.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAEL,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACb,MAAM,UAAU,CAAC;AAElB,OAAO,EAEL,kBAAkB,EAGnB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAEL,oBAAoB,EACrB,MAAM,iCAAiC,CAAC;AAMzC,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,cAAc,yBAAyB,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,mBAAmB,CAAC;IAChC,MAAM,EAAE,eAAe,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAO/F;AAQD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,YAAY,EACjB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GAClC,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAsDtE;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,mBAAmB,EAC/B,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,YAAY,GAAG,SAAS,GAC9B,OAAO,CAAC,IAAI,CAAC,CAiCf;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAG/B;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAGjC;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,kBAAkB,EAAE,EAC/B,WAAW,EAAE,oBAAoB,EAAE,EACnC,KAAK,EAAE,YAAY,GAAG,SAAS,GAC9B,OAAO,CAAC,IAAI,CAAC,CA8Cf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,KAAK,EAAE,YAAY,GAAG,SAAS,EAC/B,cAAc,EAAE,mBAAmB,EACnC,UAAU,GAAE,eAAoB,EAChC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7D,OAAO,CAAC;IACT,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,UAAU,EAAE,mBAAmB,CAAC;IAChC,MAAM,EAAE,eAAe,CAAC;CACzB,CAAC,CAgMD"}

package/dist/tracker/discovery.js

@@ -8,6 +8,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WATERMARKS_KEY = void 0;
 exports.loadWatermarks = loadWatermarks;
+exports.verifyWatermark = verifyWatermark;
 exports.saveWatermarks = saveWatermarks;
 exports.discoverProposals = discoverProposals;
 exports.discoverTimelockOps = discoverTimelockOps;
@@ -17,6 +18,7 @@ const constants_1 = require("../constants");
 const governor_discovery_1 = require("../discovery/governor-discovery");
 const timelock_discovery_1 = require("../discovery/timelock-discovery");
 const logger_1 = require("../utils/logger");
+const rpc_utils_1 = require("../utils/rpc-utils");
 const { tracker: logTracker, discovery: logDiscovery } = logger_1.loggers;
 /**
  * Cache key for discovery watermarks checkpoint.
@@ -26,20 +28,83 @@ exports.WATERMARKS_KEY = "discovery:watermarks";
 /**
  * Load discovery watermarks from cache.
  * Watermarks are stored as a TrackingCheckpoint for unified cache format.
- * Returns empty object if no watermarks are cached.
+ * Returns empty objects if no watermarks are cached.
  */
 async function loadWatermarks(cache) {
     if (!cache)
-        return {};
+        return { watermarks: {}, hashes: {} };
     const checkpoint = await cache.get(exports.WATERMARKS_KEY);
-    return checkpoint?.cachedData.discoveryWatermarks ?? {};
+    return {
+        watermarks: checkpoint?.cachedData.discoveryWatermarks ?? {},
+        hashes: checkpoint?.cachedData.watermarkHashes ?? {},
+    };
+}
+/**
+ * Number of blocks to roll back when a reorg is detected.
+ * 1000 blocks on L2 Arbitrum ≈ ~4 minutes, provides safety margin.
+ */
+const REORG_ROLLBACK_BLOCKS = 1000;
+/**
+ * Verify a watermark's block hash against the chain.
+ * If the hash doesn't match (reorg detected), returns a rolled-back block number.
+ *
+ * @param key - Watermark key for logging
+ * @param blockNumber - The watermark block number to verify
+ * @param expectedHash - The stored block hash (undefined if not stored)
+ * @param provider - Provider to fetch current block hash
+ * @returns The verified block number (original if valid, rolled back if reorg detected)
+ */
+async function verifyWatermark(key, blockNumber, expectedHash, provider) {
+    const rollback = () => ({
+        blockNumber: Math.max(0, blockNumber - REORG_ROLLBACK_BLOCKS),
+        isValid: false,
+    });
+    // No stored hash - can't verify, but fetch current hash for future verification
+    if (!expectedHash) {
+        try {
+            const block = await (0, rpc_utils_1.queryWithRetry)(() => provider.getBlock(blockNumber));
+            if (block) {
+                logDiscovery("%s: no stored hash, establishing hash at block %d", key, blockNumber);
+                return { blockNumber, isValid: true, newHash: block.hash };
+            }
+        }
+        catch {
+            // Block might not exist yet or provider error - continue without hash
+        }
+        return { blockNumber, isValid: true };
+    }
+    // Verify stored hash against chain
+    try {
+        const block = await (0, rpc_utils_1.queryWithRetry)(() => provider.getBlock(blockNumber));
+        if (!block) {
+            const result = rollback();
+            logDiscovery("%s: block %d not found, rolling back to %d", key, blockNumber, result.blockNumber);
+            return result;
+        }
+        if (block.hash.toLowerCase() === expectedHash.toLowerCase()) {
+            return { blockNumber, isValid: true, newHash: block.hash };
+        }
+        // Hash mismatch - reorg detected
+        const result = rollback();
+        logDiscovery("%s: REORG DETECTED at block %d (expected %s, got %s), rolling back to %d", key, blockNumber, expectedHash.slice(0, 10), block.hash.slice(0, 10), result.blockNumber);
+        return result;
+    }
+    catch {
+        // Provider error - be conservative and continue with stored watermark
+        logDiscovery("%s: failed to verify block %d, continuing with stored value", key, blockNumber);
+        return { blockNumber, isValid: true };
+    }
 }
 /**
  * Save discovery watermarks to cache.
  * Watermarks are stored as TrackingCheckpoint with proper metadata,
  * following the same pattern as proposal/timelock checkpoints.
+ *
+ * @param watermarks - Block numbers per discovery key
+ * @param hashes - Block hashes per discovery key (for reorg detection)
+ * @param cache - Cache adapter
  */
-async function saveWatermarks(watermarks, cache) {
+async function saveWatermarks(watermarks, hashes, cache) {
     if (!cache)
         return;
     // Calculate the max L2 block from watermarks for lastProcessedBlock
@@ -61,6 +126,7 @@ async function saveWatermarks(watermarks, cache) {
         lastProcessedBlock: { l1: 0, l2: maxL2Block },
         cachedData: {
             discoveryWatermarks: watermarks,
+            watermarkHashes: hashes,
         },
         metadata: {
             errorCount: 0,
@@ -107,13 +173,21 @@ async function discoverTimelockOps(timelockAddress, fromBlock, toBlock, l2Provid
  * 2. The monitor-loop skips timelock ops that were tracked via governor
  * 3. Creating pending checkpoints for all timelock ops causes double-counting
  */
-async function createPendingCheckpoints(proposals, _timelockOps, cache) {
+async function createPendingCheckpoints(proposals, timelockOps, cache) {
+    void timelockOps;
     if (!cache)
         return;
     let created = 0;
+    let skippedElections = 0;
     // Create pending checkpoints for proposals (if not already tracked)
     // Use tx: key format to match trackByTxHash cache keys
+    // Skip election proposals - they use election:* checkpoints
     for (const p of proposals) {
+        const proposalType = (0, governor_discovery_1.detectProposalType)(p.governorAddress);
+        if ((0, governor_discovery_1.isElectionProposal)(proposalType)) {
+            skippedElections++;
+            continue;
+        }
         const key = `tx:${p.creationTxHash.toLowerCase()}`;
         const existing = await cache.get(key);
         if (existing)
@@ -135,33 +209,73 @@ async function createPendingCheckpoints(proposals, _timelockOps, cache) {
         await cache.set(key, checkpoint);
         created++;
     }
-    if (created > 0) {
-        logDiscovery("created pending checkpoints: %d proposals", created);
+    if (created > 0 || skippedElections > 0) {
+        logDiscovery("created pending checkpoints: %d proposals (skipped %d elections)", created, skippedElections);
     }
 }
 /**
  * Discover all proposals and timelock operations with auto-watermark management.
  *
  * This is the unified discovery API that handles everything internally:
+ * - Verifies watermark hashes to detect chain reorgs (rolls back if mismatch)
  * - Loads watermarks from provided watermarks or starts from governance deployment
  * - Discovers from all enabled targets in parallel (with scoped logging)
  * - Creates pending checkpoints for discovered items
- * - Returns updated watermarks for saving
+ * - Returns updated watermarks and hashes for saving
  *
  * @param targets - Which governors/timelocks to scan
  * @param toBlock - End block for discovery
  * @param l2Provider - L2 provider
  * @param cache - Cache adapter for pending checkpoint creation
- * @param fromWatermarks - Starting watermarks
+ * @param fromWatermarks - Starting watermarks (block numbers)
+ * @param fromHashes - Starting hashes for reorg detection
  * @param options.chunkSize - Optional chunk size for log searches
- * @returns Discovered proposals, timelock ops, and updated watermarks
+ * @param options.skipReorgCheck - Skip reorg verification (for testing)
+ * @returns Discovered proposals, timelock ops, updated watermarks and hashes
  */
-async function discoverAll(targets, toBlock, l2Provider, cache, fromWatermarks, options = {}) {
-    const watermarks = fromWatermarks;
+async function discoverAll(targets, toBlock, l2Provider, cache, fromWatermarks, fromHashes = {}, options = {}) {
     const defaultStartBlock = constants_1.GOVERNANCE_START_BLOCKS.L2;
+    // Determine which keys we'll be discovering
+    const allKeys = [
+        "constitutionalGovernor",
+        "nonConstitutionalGovernor",
+        "electionNomineeGovernor",
+        "electionMemberGovernor",
+        "l2ConstitutionalTimelock",
+        "l2NonConstitutionalTimelock",
+    ];
+    const activeKeys = allKeys.filter((key) => targets[key]);
+    // Verify watermarks and get effective start blocks (with reorg detection)
+    const verifiedWatermarks = {};
+    const updatedHashes = { ...fromHashes };
+    if (!options.skipReorgCheck) {
+        // Verify all active watermarks in parallel
+        const verificationPromises = activeKeys.map(async (key) => {
+            const storedBlock = fromWatermarks[key];
+            if (storedBlock === undefined) {
+                return { key, blockNumber: defaultStartBlock };
+            }
+            const result = await verifyWatermark(key, storedBlock, fromHashes[key], l2Provider);
+            // Update hash if we got a new one
+            if (result.newHash) {
+                updatedHashes[key] = result.newHash;
+            }
+            return { key, blockNumber: result.blockNumber };
+        });
+        const verificationResults = await Promise.all(verificationPromises);
+        for (const { key, blockNumber } of verificationResults) {
+            verifiedWatermarks[key] = blockNumber;
+        }
+    }
+    else {
+        // Skip verification - use provided watermarks directly
+        for (const key of activeKeys) {
+            verifiedWatermarks[key] = fromWatermarks[key] ?? defaultStartBlock;
+        }
+    }
     // Helper to create scoped discovery task
     const scopedProposalTask = (key, scopeName, governorAddress) => {
-        const fromBlock = watermarks[key] ?? defaultStartBlock;
+        const fromBlock = verifiedWatermarks[key] ?? defaultStartBlock;
         return (0, logger_1.withScope)(scopeName, async () => {
             const proposals = await discoverProposals(governorAddress, fromBlock, toBlock, l2Provider, {
                 chunkSize: options.chunkSize,
@@ -170,7 +284,7 @@ async function discoverAll(targets, toBlock, l2Provider, cache, fromWatermarks,
         });
     };
     const scopedTimelockTask = (key, scopeName, timelockAddress) => {
-        const fromBlock = watermarks[key] ?? defaultStartBlock;
+        const fromBlock = verifiedWatermarks[key] ?? defaultStartBlock;
         return (0, logger_1.withScope)(scopeName, async () => {
             const ops = await discoverTimelockOps(timelockAddress, fromBlock, toBlock, l2Provider, {
                 chunkSize: options.chunkSize,
@@ -207,7 +321,7 @@ async function discoverAll(targets, toBlock, l2Provider, cache, fromWatermarks,
     // Collect results and update watermarks
     const allProposals = [];
     const allTimelockOps = [];
-    const newWatermarks = { ...watermarks };
+    const newWatermarks = { ...verifiedWatermarks };
     for (const { key, proposals } of proposalResults) {
         allProposals.push(...proposals);
         newWatermarks[key] = toBlock;
@@ -216,6 +330,28 @@ async function discoverAll(targets, toBlock, l2Provider, cache, fromWatermarks,
         allTimelockOps.push(...ops);
         newWatermarks[key] = toBlock;
     }
+    // Fetch toBlock hash for reorg detection on next run
+    // Only need to fetch once since all keys use the same toBlock
+    let toBlockHash;
+    if (activeKeys.length > 0) {
+        try {
+            const block = await (0, rpc_utils_1.queryWithRetry)(() => l2Provider.getBlock(toBlock));
+            if (block) {
+                toBlockHash = block.hash;
+            }
+        }
+        catch {
+            // Failed to get block hash - continue without it
+            logDiscovery("failed to fetch toBlock hash for reorg detection");
+        }
+    }
+    // Update hashes for all active keys with toBlock hash
+    const newHashes = { ...updatedHashes };
+    if (toBlockHash) {
+        for (const key of activeKeys) {
+            newHashes[key] = toBlockHash;
+        }
+    }
     // Create pending checkpoints for discovered items
     await createPendingCheckpoints(allProposals, allTimelockOps, cache);
     logDiscovery("complete: %d proposals, %d timelockOps", allProposals.length, allTimelockOps.length);
@@ -223,6 +359,7 @@ async function discoverAll(targets, toBlock, l2Provider, cache, fromWatermarks,
         proposals: allProposals,
         timelockOps: allTimelockOps,
         watermarks: newWatermarks,
+        hashes: newHashes,
     };
 }
 //# sourceMappingURL=discovery.js.map