@gzeoneth/gov-tracker 0.1.0

package/dist/tracker/state.js

@@ -0,0 +1,287 @@
+"use strict";
+/**
+ * Cache utilities for tracker state
+ *
+ * Provides cache implementations and utility functions.
+ * All other state management is handled directly in tracker.ts.
+ *
+ * Available cache adapters:
+ * - FileCache: File-based persistence (Node.js only)
+ * - LocalStorageCache: Browser localStorage (web only)
+ * - MemoryCache: In-memory, no persistence (universal)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryCache = exports.LocalStorageCache = exports.FileCache = void 0;
+exports.txHashCacheKey = txHashCacheKey;
+exports.readCacheStatus = readCacheStatus;
+const fs = __importStar(require("fs"));
+const discovery_1 = require("./discovery");
+/**
+ * File-based cache that persists to JSON file.
+ * Synchronously loads on construction, persists on every write.
+ * Uses a write queue to prevent race conditions from concurrent writes.
+ */
+class FileCache {
+    constructor(path) {
+        this.writeQueue = Promise.resolve();
+        this.path = path;
+        this.cache = this.load();
+    }
+    load() {
+        try {
+            const data = JSON.parse(fs.readFileSync(this.path, "utf8"));
+            return new Map(Object.entries(data));
+        }
+        catch {
+            return new Map();
+        }
+    }
+    persistSync() {
+        const obj = Object.fromEntries(this.cache);
+        fs.writeFileSync(this.path, JSON.stringify(obj, null, 2));
+    }
+    async persist() {
+        // Chain writes to prevent race conditions
+        // Create the write promise that may reject on error
+        const writePromise = this.writeQueue.then(() => {
+            this.persistSync();
+        });
+        // Update the queue with error recovery to prevent getting stuck
+        // This ensures future writes can proceed even if this one fails
+        this.writeQueue = writePromise.catch(() => {
+            // Silently recover the queue - error is propagated via writePromise
+        });
+        // Return the original promise so errors propagate to caller
+        return writePromise;
+    }
+    async get(key) {
+        return this.cache.get(key) ?? null;
+    }
+    async set(key, value) {
+        this.cache.set(key, value);
+        await this.persist();
+    }
+    async delete(key) {
+        this.cache.delete(key);
+        await this.persist();
+    }
+    async clear() {
+        this.cache.clear();
+        await this.persist();
+    }
+    async has(key) {
+        return this.cache.has(key);
+    }
+    keys() {
+        return this.cache.keys();
+    }
+}
+exports.FileCache = FileCache;
+/**
+ * Get localStorage if available (browser environment)
+ */
+function getLocalStorage() {
+    // Check for browser environment with localStorage
+    if (typeof globalThis !== "undefined") {
+        const global = globalThis;
+        if (typeof global.localStorage !== "undefined") {
+            return global.localStorage;
+        }
+    }
+    return null;
+}
+/**
+ * Browser localStorage-based cache adapter.
+ * Persists to localStorage with a configurable key prefix.
+ *
+ * Limitations:
+ * - 5MB storage limit (varies by browser)
+ * - Synchronous API (blocks main thread, usually negligible)
+ * - String-only storage (JSON serialization handled internally)
+ *
+ * @example
+ * ```typescript
+ * import { createTracker, LocalStorageCache } from "@gzeoneth/gov-tracker";
+ *
+ * const tracker = createTracker({
+ *   l2Provider,
+ *   l1Provider,
+ *   cache: new LocalStorageCache("arb-gov:"),
+ * });
+ * ```
+ */
+class LocalStorageCache {
+    constructor(prefix = "tracker:") {
+        this.prefix = prefix;
+    }
+    fullKey(key) {
+        return `${this.prefix}${key}`;
+    }
+    async get(key) {
+        const storage = getLocalStorage();
+        if (!storage)
+            return null;
+        const data = storage.getItem(this.fullKey(key));
+        if (data === null)
+            return null;
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            return null;
+        }
+    }
+    async set(key, value) {
+        const storage = getLocalStorage();
+        if (!storage)
+            return;
+        storage.setItem(this.fullKey(key), JSON.stringify(value));
+    }
+    async delete(key) {
+        const storage = getLocalStorage();
+        if (!storage)
+            return;
+        storage.removeItem(this.fullKey(key));
+    }
+    async clear() {
+        const storage = getLocalStorage();
+        if (!storage)
+            return;
+        const keysToRemove = [];
+        for (let i = 0; i < storage.length; i++) {
+            const key = storage.key(i);
+            if (key?.startsWith(this.prefix)) {
+                keysToRemove.push(key);
+            }
+        }
+        keysToRemove.forEach((k) => storage.removeItem(k));
+    }
+    async has(key) {
+        const storage = getLocalStorage();
+        if (!storage)
+            return false;
+        return storage.getItem(this.fullKey(key)) !== null;
+    }
+    async keys(prefix) {
+        const storage = getLocalStorage();
+        if (!storage)
+            return [];
+        const result = [];
+        for (let i = 0; i < storage.length; i++) {
+            const fullKey = storage.key(i);
+            if (fullKey?.startsWith(this.prefix)) {
+                const key = fullKey.slice(this.prefix.length);
+                if (!prefix || key.startsWith(prefix)) {
+                    result.push(key);
+                }
+            }
+        }
+        return result;
+    }
+}
+exports.LocalStorageCache = LocalStorageCache;
+/**
+ * In-memory cache adapter with no persistence.
+ * Useful for testing, short-lived sessions, or as a fallback.
+ *
+ * Data is lost when the page is refreshed or the process exits.
+ *
+ * @example
+ * ```typescript
+ * import { createTracker, MemoryCache } from "@gzeoneth/gov-tracker";
+ *
+ * const tracker = createTracker({
+ *   l2Provider,
+ *   l1Provider,
+ *   cache: new MemoryCache(),
+ * });
+ * ```
+ */
+class MemoryCache {
+    constructor() {
+        this.cache = new Map();
+    }
+    async get(key) {
+        return this.cache.get(key) ?? null;
+    }
+    async set(key, value) {
+        this.cache.set(key, value);
+    }
+    async delete(key) {
+        this.cache.delete(key);
+    }
+    async clear() {
+        this.cache.clear();
+    }
+    async has(key) {
+        return this.cache.has(key);
+    }
+    keys() {
+        return this.cache.keys();
+    }
+}
+exports.MemoryCache = MemoryCache;
+/**
+ * Generate cache key from transaction hash (primary cache key format)
+ */
+function txHashCacheKey(txHash) {
+    return `tx:${txHash.toLowerCase()}`;
+}
+/**
+ * Read all cache data without requiring RPC providers.
+ * Use this for status/dashboard views that only need cached data.
+ *
+ * @param cachePath - Path to the cache file
+ */
+async function readCacheStatus(cachePath) {
+    const cache = new FileCache(cachePath);
+    // Load watermarks from discovery checkpoint (unified format)
+    const discoveryCheckpoint = await cache.get(discovery_1.WATERMARKS_KEY);
+    const watermarks = discoveryCheckpoint?.cachedData.discoveryWatermarks ?? {};
+    const checkpoints = new Map();
+    const allKeys = cache.keys();
+    const keys = Array.isArray(allKeys) ? allKeys : Array.from(allKeys);
+    for (const key of keys) {
+        if (key.startsWith("tx:")) {
+            const checkpoint = await cache.get(key);
+            if (checkpoint) {
+                checkpoints.set(key, checkpoint);
+            }
+        }
+    }
+    return { watermarks, checkpoints };
+}
+//# sourceMappingURL=state.js.map

package/dist/tracker/state.js.map

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

package/dist/tracker.d.ts

@@ -0,0 +1,261 @@
+/**
+ * ProposalStageTracker - Main entry point
+ *
+ * Tracks Arbitrum governance proposal lifecycle stages from
+ * either a governor proposal or a timelock operation.
+ *
+ * This file is the public API that composes focused modules:
+ * - tracker/context.ts: Functional TrackingContext for stage tracking
+ * - tracker/pipeline.ts: Pure functions that track stages
+ * - tracker/discovery.ts: Proposal and timelock discovery
+ * - tracker/query.ts: Checkpoint query operations
+ * - tracker/execute.ts: Transaction preparation
+ */
+import { ethers } from "ethers";
+import { TrackerOptions, TrackingResult, TrackedStage, TrackingCheckpoint, TrackerStats, ChunkingConfig, DiscoveryWatermarks, DiscoveryTargets, PrepareResult, PrepareOptions, ElectionCheckResult, TimelockLink } from "./types";
+import { DiscoveredProposal, DiscoveredTimelockOp } from "./tracker/discovery";
+/**
+ * Extract TimelockLink from stages if PROPOSAL_QUEUED is completed
+ */
+export declare function extractTimelockLink(stages: TrackedStage[]): TimelockLink | undefined;
+/**
+ * Main proposal stage tracker class
+ *
+ * @example
+ * ```typescript
+ * const tracker = new ProposalStageTracker({
+ *   l2Provider: new ethers.providers.JsonRpcProvider(ARB1_RPC),
+ *   l1Provider: new ethers.providers.JsonRpcProvider(ETH_RPC),
+ * });
+ *
+ * // Track by transaction hash (recommended)
+ * const results = await tracker.trackByTxHash(creationTxHash);
+ *
+ * for (const stage of results[0].stages) {
+ *   console.log(`${stage.type}: ${stage.status}`);
+ * }
+ *
+ * // Resume from checkpoint
+ * const resumedTracker = createTracker({
+ *   l2Provider,
+ *   l1Provider,
+ *   checkpoint: savedCheckpoint
+ * });
+ * const fresh = await resumedTracker.trackByTxHash(creationTxHash);
+ * ```
+ */
+export declare class ProposalStageTracker {
+    private l2Provider;
+    private l1Provider;
+    private novaProvider;
+    private onProgress?;
+    /** Chunking configuration for log searches */
+    readonly chunkingConfig: ChunkingConfig;
+    /** Cache adapter for checkpoint persistence */
+    private cache?;
+    constructor(options: TrackerOptions);
+    /**
+     * Read all cache data without requiring RPC providers.
+     * Use this for status/dashboard views that only need cached data.
+     *
+     * This is the ONLY way to access cache data outside of a full tracker instance.
+     * All cache access goes through this class to maintain single-system ownership.
+     *
+     * @param cachePath - Path to the cache file (tracker creates FileCache internally)
+     */
+    static readCacheStatus(cachePath: string): Promise<{
+        watermarks: DiscoveryWatermarks;
+        checkpoints: Map<string, TrackingCheckpoint>;
+    }>;
+    /**
+     * Load discovery watermarks from cache.
+     * Watermarks are stored as a TrackingCheckpoint for unified cache format.
+     * Returns empty object if no watermarks are cached.
+     */
+    loadWatermarks(): Promise<DiscoveryWatermarks>;
+    /**
+     * Save discovery watermarks to cache.
+     * Watermarks are stored as TrackingCheckpoint with proper metadata,
+     * following the same pattern as proposal/timelock checkpoints.
+     */
+    saveWatermarks(watermarks: DiscoveryWatermarks): Promise<void>;
+    /**
+     * Discover proposals from a governor in a block range.
+     *
+     * @param governorAddress - Governor contract address
+     * @param fromBlock - Start block (exclusive - searches from fromBlock + 1)
+     * @param toBlock - End block (inclusive)
+     * @returns Array of discovered proposals
+     */
+    discoverProposals(governorAddress: string, fromBlock: number, toBlock: number): Promise<DiscoveredProposal[]>;
+    /**
+     * Discover timelock operations from a timelock in a block range.
+     *
+     * @param timelockAddress - Timelock contract address
+     * @param fromBlock - Start block (exclusive - searches from fromBlock + 1)
+     * @param toBlock - End block (inclusive)
+     * @returns Array of discovered timelock operations
+     */
+    discoverTimelockOps(timelockAddress: string, fromBlock: number, toBlock: number): Promise<DiscoveredTimelockOp[]>;
+    /**
+     * Discover all proposals and timelock operations with auto-watermark management.
+     *
+     * This is the unified discovery API that handles everything internally:
+     * - Loads watermarks from cache (or uses provided fromWatermarks)
+     * - Discovers from all enabled targets in parallel
+     * - Auto-saves updated watermarks to cache
+     *
+     * @param targets - Which governors/timelocks to scan
+     * @param toBlock - End block for discovery
+     * @param fromWatermarks - Optional starting watermarks (overrides cached watermarks)
+     * @returns Discovered proposals, timelock ops, and updated watermarks
+     */
+    discoverAll(targets: DiscoveryTargets, toBlock: number, fromWatermarks?: DiscoveryWatermarks): Promise<{
+        proposals: DiscoveredProposal[];
+        timelockOps: DiscoveredTimelockOp[];
+        watermarks: DiscoveryWatermarks;
+    }>;
+    /**
+     * List all checkpoint keys in the cache.
+     */
+    listCheckpointKeys(): Promise<string[]>;
+    /**
+     * Get a specific checkpoint from cache by key.
+     */
+    getCheckpoint(key: string): Promise<TrackingCheckpoint | null>;
+    /**
+     * Get all checkpoints from cache.
+     */
+    getAllCheckpoints(): Promise<Map<string, TrackingCheckpoint>>;
+    /**
+     * Query incomplete checkpoints that should be re-tracked.
+     *
+     * @param options.maxAgeDays - Skip items older than this (default: 60)
+     * @param options.maxErrorCount - Skip items with more consecutive errors (default: 5)
+     */
+    queryIncompleteCheckpoints(options?: {
+        maxAgeDays?: number;
+        maxErrorCount?: number;
+    }): Promise<Array<{
+        key: string;
+        checkpoint: TrackingCheckpoint;
+    }>>;
+    /**
+     * Get aggregated cache statistics.
+     *
+     * @param maxErrorCount - Items with this many or more errors are counted as "errored" (default: 5)
+     */
+    getStats(maxErrorCount?: number): Promise<TrackerStats>;
+    /**
+     * Track from transaction hash (primary tracking entry point)
+     *
+     * Auto-detects whether the transaction contains a governor proposal or
+     * timelock operations and tracks accordingly.
+     *
+     * Returns an array because a single transaction may contain multiple
+     * timelock operations (e.g., SC rotation with 4 operations).
+     *
+     * When cache is configured on the tracker:
+     * - Automatically loads existing checkpoint from cache (zero-RPC resume)
+     * - Automatically saves checkpoint to cache after tracking
+     *
+     * @example
+     * ```typescript
+     * const results = await tracker.trackByTxHash("0x...");
+     * for (const result of results) {
+     *   console.log(`Found ${result.stages.length} stages`);
+     * }
+     * ```
+     */
+    trackByTxHash(txHash: string): Promise<TrackingResult[]>;
+    /**
+     * Internal implementation of trackByTxHash.
+     *
+     * Uses PipelineContext for stateful tracking - no parameter passing between stages.
+     */
+    private trackByTxHashInternal;
+    /**
+     * Track governor proposal using TrackingContext (stateful tracking)
+     */
+    private trackGovernorWithPipeline;
+    /**
+     * Track timelock operation using TrackingContext (stateful tracking)
+     */
+    private trackTimelockWithPipeline;
+    /**
+     * Build TrackingResult from TrackingContext
+     */
+    private buildResultFromState;
+    /**
+     * Track from a cached checkpoint.
+     *
+     * This is a convenience method that extracts the transaction hash from the
+     * checkpoint and dispatches to trackByTxHash. Use this when re-tracking
+     * items from queryIncompleteCheckpoints().
+     *
+     * @example
+     * ```typescript
+     * const incomplete = await tracker.queryIncompleteCheckpoints({ maxAgeDays: 60 });
+     * for (const { checkpoint } of incomplete) {
+     *   const result = await tracker.trackFromCheckpoint(checkpoint);
+     *   // ... handle result
+     * }
+     * ```
+     */
+    trackFromCheckpoint(checkpoint: TrackingCheckpoint): Promise<TrackingResult>;
+    /**
+     * Prepare a transaction for a READY stage without sending it.
+     *
+     * Returns PrepareResult with the prepared transaction data.
+     * Consumer is responsible for signing and sending the transaction.
+     *
+     * @param stage - The stage to prepare
+     * @param options - Preparation options
+     * @param allStages - Optional array of all stages (used to extract description for salt resolution)
+     *
+     * @example
+     * ```typescript
+     * const result = await tracker.prepareTransaction(readyStage);
+     * if (result.success) {
+     *   console.log(`To: ${result.prepared.to}`);
+     *   console.log(`Data: ${result.prepared.data}`);
+     *   console.log(`Chain: ${result.prepared.chain}`);
+     *
+     *   // Execute with your own signer
+     *   const tx = await signer.sendTransaction({
+     *     to: result.prepared.to,
+     *     data: result.prepared.data,
+     *     value: result.prepared.value,
+     *   });
+     *   await tx.wait();
+     * } else {
+     *   console.error(result.error);
+     * }
+     * ```
+     *
+     * @note Salt is now pre-computed during tracking and stored in stage.data
+     */
+    prepareTransaction(stage: TrackedStage, options?: PrepareOptions): Promise<PrepareResult>;
+    /**
+     * Get the current providers
+     */
+    getProviders(): {
+        l1: ethers.providers.Provider;
+        l2: ethers.providers.Provider;
+        nova?: ethers.providers.Provider;
+    };
+    /**
+     * Check Security Council election status and prepare available actions
+     *
+     * @param options.nomineeGovernorAddress - Override the nominee election governor address
+     * @returns Election status with prepared transactions for available actions
+     */
+    checkElection(options?: {
+        nomineeGovernorAddress?: string;
+    }): Promise<ElectionCheckResult>;
+}
+/**
+ * Factory function to create a tracker instance
+ */
+export declare function createTracker(options: TrackerOptions): ProposalStageTracker;
+//# sourceMappingURL=tracker.d.ts.map

package/dist/tracker.d.ts.map

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