@gzeoneth/gov-tracker 0.1.0

package/dist/tracker/pipeline.js

@@ -0,0 +1,299 @@
+"use strict";
+/**
+ * Pipeline Stage Functions
+ *
+ * Pure functions that track stages and return updated state.
+ * Each function reads from state, performs tracking, and returns new state.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pipelineTrackProposalCreated = pipelineTrackProposalCreated;
+exports.pipelineTrackVoting = pipelineTrackVoting;
+exports.pipelineTrackProposalQueued = pipelineTrackProposalQueued;
+exports.pipelineTrackL2Timelock = pipelineTrackL2Timelock;
+exports.pipelineTrackL2ToL1Message = pipelineTrackL2ToL1Message;
+exports.pipelineTrackL1Timelock = pipelineTrackL1Timelock;
+exports.pipelineTrackRetryables = pipelineTrackRetryables;
+exports.trackGovernorPipeline = trackGovernorPipeline;
+exports.trackTimelockPipeline = trackTimelockPipeline;
+const logger_1 = require("../utils/logger");
+const context_1 = require("./context");
+const base_1 = require("../stages/base");
+const proposal_created_1 = require("../stages/proposal-created");
+const voting_1 = require("../stages/voting");
+const proposal_queued_1 = require("../stages/proposal-queued");
+const timing_1 = require("../utils/timing");
+const timelock_1 = require("../stages/timelock");
+const l2_to_l1_message_1 = require("../stages/l2-to-l1-message");
+const retryables_1 = require("../stages/retryables");
+const constants_1 = require("../constants");
+const timing_2 = require("../utils/timing");
+// Logging
+const { pipeline: log, tracker: logTracker } = logger_1.loggers;
+// Stage chain mapping for L1 stages
+// L1_TIMELOCK is the only L1 stage; RETRYABLE_EXECUTED runs on L2 (Arb1/Nova)
+const L1_STAGES = new Set(["L1_TIMELOCK"]);
+// Helper: create placeholder stage
+const placeholder = (type, status, reason) => ({
+    type,
+    status,
+    chain: L1_STAGES.has(type) ? "L1" : "L2",
+    transactions: [],
+    data: { reason },
+});
+// Helper: track with cache check
+async function withCache(state, stageType, key, onCached, onTrack) {
+    const cached = (0, context_1.getCompletedStage)(state, stageType);
+    if (cached) {
+        log("%s: using cached stage", stageType);
+        return { state: await (0, context_1.addStage)(state, cached), [key]: onCached(cached) };
+    }
+    return onTrack();
+}
+// Helper: track stage with error handling
+async function track(state, stageType, key, tracker) {
+    try {
+        const { stage, result } = await tracker();
+        return { state: await (0, context_1.addStage)(state, stage), [key]: result };
+    }
+    catch (error) {
+        throw new Error(`Failed to track ${stageType}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+// Governor Stages (1-3)
+async function pipelineTrackProposalCreated(state) {
+    const governorAddress = (0, context_1.getGovernorAddress)(state);
+    const proposalId = (0, context_1.getProposalId)(state);
+    if (!governorAddress || !proposalId)
+        return { state, found: false };
+    if ((0, context_1.getIsElection)(state))
+        return { state, found: false };
+    return withCache(state, "PROPOSAL_CREATED", "found", () => true, async () => {
+        log("PROPOSAL_CREATED: tracking");
+        const creationTxHash = state.input.type === "governor" ? state.input.creationTxHash : undefined;
+        return track(state, "PROPOSAL_CREATED", "found", async () => {
+            const r = await (0, proposal_created_1.trackProposalCreated)(governorAddress, proposalId, state.providers.l2, {
+                creationTxHash,
+            });
+            return { stage: r.stage, result: r.proposalData !== null };
+        });
+    });
+}
+async function pipelineTrackVoting(state) {
+    const governorAddress = (0, context_1.getGovernorAddress)(state);
+    const proposalId = (0, context_1.getProposalId)(state);
+    const proposalData = (0, context_1.getProposalData)(state);
+    if (!governorAddress || !proposalId || !proposalData)
+        return { state, complete: false };
+    return withCache(state, "VOTING_ACTIVE", "complete", (c) => c.status === "COMPLETED", async () => {
+        log("VOTING_ACTIVE: tracking");
+        return track(state, "VOTING_ACTIVE", "complete", async () => {
+            const r = await (0, voting_1.trackVotingStage)(governorAddress, proposalId, proposalData, state.providers.l2);
+            return { stage: r.stage, result: r.stage.status === "COMPLETED" };
+        });
+    });
+}
+async function pipelineTrackProposalQueued(state) {
+    const governorAddress = (0, context_1.getGovernorAddress)(state);
+    const proposalId = (0, context_1.getProposalId)(state);
+    const proposalData = (0, context_1.getProposalData)(state);
+    if (!governorAddress || !proposalId)
+        return { state, queued: false };
+    return withCache(state, "PROPOSAL_QUEUED", "queued", () => true, async () => {
+        log("PROPOSAL_QUEUED: tracking");
+        return track(state, "PROPOSAL_QUEUED", "queued", async () => {
+            // Voting deadline is L1 block number - convert to L2 for searching
+            // Use bounds to speed up binary search: min=creation block, max=creation+7M (~20 days)
+            const votingDeadlineL1 = (0, context_1.getVotingEndBlock)(state);
+            let votingEndBlock;
+            if (votingDeadlineL1) {
+                const creationBlock = proposalData?.creationBlock ?? 0;
+                const { blockNumber: currentL2Block } = await (0, timing_2.getCurrentBlockInfo)(state.providers.l2);
+                const maxL2Block = Math.min(creationBlock + 7000000, currentL2Block);
+                votingEndBlock = await (0, timing_1.getFirstL2BlockForL1Block)(state.providers.l2, votingDeadlineL1, {
+                    minL2Block: creationBlock,
+                    maxL2Block,
+                });
+            }
+            const r = await (0, proposal_queued_1.trackProposalQueued)(governorAddress, proposalId, state.providers.l2, proposalData?.creationBlock ?? 0, { votingEndBlock });
+            let stage = r.stage;
+            if (stage.status === "READY" && proposalData) {
+                stage = {
+                    ...stage,
+                    data: {
+                        ...stage.data,
+                        targets: proposalData.targets,
+                        values: Array.from(proposalData.values).map((v) => v.toString()),
+                        calldatas: proposalData.calldatas,
+                        description: proposalData.description,
+                    },
+                };
+            }
+            return { stage, result: r.operationId !== null && r.timelockAddress !== null };
+        });
+    });
+}
+// Timelock Stage (4)
+async function pipelineTrackL2Timelock(state) {
+    const timelockAddress = (0, context_1.getTimelockAddress)(state);
+    const operationId = (0, context_1.getOperationId)(state);
+    const firstCallScheduledData = (0, context_1.getFirstCallScheduledData)(state);
+    if (!timelockAddress || !operationId || !firstCallScheduledData)
+        return { state, executed: false };
+    return withCache(state, "L2_TIMELOCK", "executed", (c) => c.status === "COMPLETED", async () => {
+        log("L2_TIMELOCK: tracking");
+        return track(state, "L2_TIMELOCK", "executed", async () => {
+            const r = await (0, timelock_1.trackL2Timelock)(timelockAddress, operationId, state.providers.l2, (0, context_1.getQueueBlockNumber)(state) ?? 0, firstCallScheduledData, {
+                cachedExecutionTxHash: (0, context_1.getL2ExecutionTxHash)(state),
+                allStages: state.stages,
+            });
+            return { stage: r.stage, result: r.executionTxHash !== null };
+        });
+    });
+}
+// L2→L1 Message Stage (5) - Unified
+const L1_ROUNDTRIP_STAGES = ["L2_TO_L1_MESSAGE", "L1_TIMELOCK", "RETRYABLE_EXECUTED"];
+async function addSkippedL1Stages(state) {
+    let s = state;
+    for (const type of L1_ROUNDTRIP_STAGES)
+        s = await (0, context_1.addStage)(s, placeholder(type, "SKIPPED", "L2-only path"));
+    return s;
+}
+async function pipelineTrackL2ToL1Message(state) {
+    const l2ExecutionTxHash = (0, context_1.getL2ExecutionTxHash)(state);
+    const addressForPath = (0, context_1.getGovernorAddress)(state) ?? (0, context_1.getTimelockAddress)(state);
+    const needsL1 = addressForPath ? (0, base_1.isConstitutional)(addressForPath) : true;
+    if (!needsL1) {
+        log("L2_TO_L1_MESSAGE: L2-only path, skipping L1 stages");
+        return { state: await addSkippedL1Stages(state), executed: false, needsL1: false };
+    }
+    if (!l2ExecutionTxHash)
+        return { state, executed: false, needsL1: true };
+    // Check completed cache
+    const cached = (0, context_1.getCompletedStage)(state, "L2_TO_L1_MESSAGE");
+    if (cached) {
+        log("L2_TO_L1_MESSAGE: using cached stage");
+        return { state: await (0, context_1.addStage)(state, cached), executed: true, needsL1: true };
+    }
+    // Fast-path for pending (still in challenge period)
+    const pending = (0, context_1.getCachedStage)(state, "L2_TO_L1_MESSAGE");
+    if (pending?.status === "PENDING") {
+        const firstExec = pending.data.firstExecutableBlock;
+        if (firstExec) {
+            const { blockNumber: currentL1Block, timestamp } = await (0, timing_2.getCurrentBlockInfo)(state.providers.l1);
+            if (currentL1Block < firstExec) {
+                const remainingSeconds = (firstExec - currentL1Block) * constants_1.BLOCK_TIMES.L1;
+                const updated = {
+                    ...pending,
+                    data: { ...pending.data, currentL1Block, fastPath: true },
+                    timing: {
+                        ...pending.timing,
+                        eta: timestamp + remainingSeconds,
+                        delaySeconds: remainingSeconds,
+                    },
+                };
+                return { state: await (0, context_1.addStage)(state, updated), executed: false, needsL1: true };
+            }
+        }
+    }
+    // Full tracking
+    log("L2_TO_L1_MESSAGE: tracking");
+    const { state: newState, executed } = await track(state, "L2_TO_L1_MESSAGE", "executed", async () => {
+        const r = await (0, l2_to_l1_message_1.trackL2ToL1Message)(l2ExecutionTxHash, state.providers.l2, state.providers.l1);
+        return { stage: r.stage, result: r.isExecuted };
+    });
+    return { state: newState, executed, needsL1: true };
+}
+// L1 Timelock Stage (6)
+async function pipelineTrackL1Timelock(state) {
+    return withCache(state, "L1_TIMELOCK", "executed", (c) => c.status === "COMPLETED", async () => {
+        log("L1_TIMELOCK: tracking");
+        return track(state, "L1_TIMELOCK", "executed", async () => {
+            const r = await (0, timelock_1.trackL1Timelock)(state.providers.l1, {
+                outboxExecutionTx: (0, context_1.getOutboxExecutionTx)(state),
+                fromBlock: (0, context_1.getFirstExecutableBlock)(state),
+                allStages: state.stages,
+            });
+            return { stage: r.stage, result: r.executionTxHash !== null };
+        });
+    });
+}
+// Retryable Stage (7)
+async function pipelineTrackRetryables(state) {
+    const l1ExecutionTxHash = (0, context_1.getL1ExecutionTxHash)(state);
+    if (!l1ExecutionTxHash)
+        return { state, redeemed: false };
+    return withCache(state, "RETRYABLE_EXECUTED", "redeemed", (c) => c.status === "COMPLETED", async () => {
+        log("RETRYABLE_EXECUTED: tracking");
+        return track(state, "RETRYABLE_EXECUTED", "redeemed", async () => {
+            const r = await (0, retryables_1.trackRetryables)(l1ExecutionTxHash, state.providers.l1, {
+                l2Provider: state.providers.l2,
+                novaProvider: state.providers.nova,
+            });
+            return { stage: r.stage, result: r.stage.status === "COMPLETED" };
+        });
+    });
+}
+// Full Pipelines
+async function addPlaceholders(state, types, reason) {
+    let s = state;
+    for (const type of types)
+        s = await (0, context_1.addStage)(s, placeholder(type, "NOT_STARTED", reason));
+    return s;
+}
+const RETRYABLE_STAGES = ["RETRYABLE_EXECUTED"];
+/**
+ * Track full governor proposal pipeline.
+ * Returns final state after tracking all stages.
+ */
+async function trackGovernorPipeline(state) {
+    // Stage 1: Proposal Created
+    const { state: state1, found } = await pipelineTrackProposalCreated(state);
+    if (!found) {
+        logTracker("proposal not found, stopping");
+        return state1;
+    }
+    // Stage 2: Voting
+    const { state: state2, complete: votingComplete } = await pipelineTrackVoting(state1);
+    if (!votingComplete) {
+        logTracker("voting not complete, stopping");
+        return state2;
+    }
+    // Stage 3: Proposal Queued
+    const { state: state3, queued } = await pipelineTrackProposalQueued(state2);
+    if (!queued) {
+        logTracker("proposal not queued, stopping");
+        return state3;
+    }
+    // Continue with timelock pipeline
+    return trackTimelockPipeline(state3);
+}
+/**
+ * Track timelock pipeline (stages 4-7).
+ * Used by governor pipeline and direct timelock tracking.
+ */
+async function trackTimelockPipeline(state) {
+    // Stage 4: L2 Timelock (unified)
+    const { state: state1, executed: l2Executed } = await pipelineTrackL2Timelock(state);
+    if (!l2Executed) {
+        logTracker("L2 timelock not executed, stopping");
+        return addPlaceholders(state1, L1_ROUNDTRIP_STAGES, "L2 timelock not executed");
+    }
+    // Stage 5: L2→L1 Message (unified)
+    const { state: state2, executed: msgExecuted, needsL1, } = await pipelineTrackL2ToL1Message(state1);
+    if (!needsL1)
+        return state2; // L2-only path, already added SKIPPED stages
+    if (!msgExecuted) {
+        logTracker("L2→L1 message not executed, stopping");
+        return addPlaceholders(state2, L1_ROUNDTRIP_STAGES.slice(1), "Waiting for L2→L1 message");
+    }
+    // Stage 6: L1 Timelock (unified)
+    const { state: state3, executed: l1Executed } = await pipelineTrackL1Timelock(state2);
+    if (!l1Executed) {
+        logTracker("L1 timelock not executed, stopping");
+        return addPlaceholders(state3, RETRYABLE_STAGES, "L1 timelock not executed");
+    }
+    // Stage 7: Retryables
+    const { state: finalState } = await pipelineTrackRetryables(state3);
+    return finalState;
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/tracker/pipeline.js.map

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

package/dist/tracker/query.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Tracker Query Module
+ *
+ * Provides checkpoint query and statistics operations.
+ * Includes filtering, aggregation, and cache introspection.
+ */
+import { TrackingCheckpoint, TrackerStats, CacheAdapter } from "../types";
+/**
+ * List all checkpoint keys in the cache.
+ * @param cache - Cache adapter to query
+ */
+export declare function listCheckpointKeys(cache: CacheAdapter | undefined): Promise<string[]>;
+/**
+ * Get a specific checkpoint from cache by key.
+ */
+export declare function getCheckpoint(cache: CacheAdapter | undefined, key: string): Promise<TrackingCheckpoint | null>;
+/**
+ * Get all checkpoints from cache.
+ */
+export declare function getAllCheckpoints(cache: CacheAdapter | undefined): Promise<Map<string, TrackingCheckpoint>>;
+/**
+ * Query incomplete checkpoints that should be re-tracked.
+ *
+ * @param cache - Cache adapter to query
+ * @param options.maxAgeDays - Skip items older than this (default: 60)
+ * @param options.maxErrorCount - Skip items with more consecutive errors (default: 5)
+ */
+export declare function queryIncompleteCheckpoints(cache: CacheAdapter | undefined, options?: {
+    maxAgeDays?: number;
+    maxErrorCount?: number;
+}): Promise<Array<{
+    key: string;
+    checkpoint: TrackingCheckpoint;
+}>>;
+/**
+ * Get aggregated cache statistics.
+ *
+ * Provides a summary of all cached proposals, timelock operations, and elections
+ * without making any RPC calls. Useful for dashboards and status displays.
+ *
+ * @param cache - Cache adapter to query
+ * @param maxErrorCount - Items with this many or more errors are counted as "errored" (default: 5)
+ */
+export declare function getStats(cache: CacheAdapter | undefined, maxErrorCount?: number): Promise<TrackerStats>;
+//# sourceMappingURL=query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/tracker/query.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAI1E;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAM3F;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,YAAY,GAAG,SAAS,EAC/B,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAGpC;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,YAAY,GAAG,SAAS,GAC9B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAU1C;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,YAAY,GAAG,SAAS,EAC/B,OAAO,GAAE;IACP,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACnB,GACL,OAAO,CAAC,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAAC,CA0CjE;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,YAAY,GAAG,SAAS,EAC/B,aAAa,GAAE,MAAU,GACxB,OAAO,CAAC,YAAY,CAAC,CA6DvB"}

package/dist/tracker/query.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Tracker Query Module
+ *
+ * Provides checkpoint query and statistics operations.
+ * Includes filtering, aggregation, and cache introspection.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listCheckpointKeys = listCheckpointKeys;
+exports.getCheckpoint = getCheckpoint;
+exports.getAllCheckpoints = getAllCheckpoints;
+exports.queryIncompleteCheckpoints = queryIncompleteCheckpoints;
+exports.getStats = getStats;
+const base_1 = require("../stages/base");
+const constants_1 = require("../constants");
+/**
+ * List all checkpoint keys in the cache.
+ * @param cache - Cache adapter to query
+ */
+async function listCheckpointKeys(cache) {
+    if (!cache)
+        return [];
+    const allKeys = await cache.keys();
+    const keys = Array.isArray(allKeys) ? allKeys : Array.from(allKeys);
+    // All tracking checkpoints use tx: prefix
+    return keys.filter((k) => k.startsWith("tx:"));
+}
+/**
+ * Get a specific checkpoint from cache by key.
+ */
+async function getCheckpoint(cache, key) {
+    if (!cache)
+        return null;
+    return await cache.get(key);
+}
+/**
+ * Get all checkpoints from cache.
+ */
+async function getAllCheckpoints(cache) {
+    const map = new Map();
+    const keys = await listCheckpointKeys(cache);
+    for (const key of keys) {
+        const checkpoint = await getCheckpoint(cache, key);
+        if (checkpoint) {
+            map.set(key, checkpoint);
+        }
+    }
+    return map;
+}
+/**
+ * Query incomplete checkpoints that should be re-tracked.
+ *
+ * @param cache - Cache adapter to query
+ * @param options.maxAgeDays - Skip items older than this (default: 60)
+ * @param options.maxErrorCount - Skip items with more consecutive errors (default: 5)
+ */
+async function queryIncompleteCheckpoints(cache, options = {}) {
+    const maxAgeDays = options.maxAgeDays ?? 60;
+    const maxErrorCount = options.maxErrorCount ?? 5;
+    const maxAgeMs = maxAgeDays * 24 * 60 * 60 * 1000;
+    const now = Date.now();
+    const results = [];
+    const keys = await listCheckpointKeys(cache);
+    for (const key of keys) {
+        const checkpoint = await getCheckpoint(cache, key);
+        if (!checkpoint)
+            continue;
+        const errorCount = checkpoint.metadata?.errorCount ?? 0;
+        const completedStages = checkpoint.cachedData.completedStages ?? [];
+        // Skip if already complete
+        if (completedStages.length > 0 && (0, base_1.areAllStagesComplete)(completedStages)) {
+            continue;
+        }
+        // Skip if voting failed (terminal state)
+        const votingStage = completedStages.find((s) => s.type === "VOTING_ACTIVE");
+        if (votingStage?.status === "FAILED") {
+            continue;
+        }
+        // Skip if exceeded error threshold
+        if (errorCount >= maxErrorCount) {
+            continue;
+        }
+        // Skip if too old
+        const createdAt = checkpoint.createdAt ?? 0;
+        if (createdAt > 0 && now - createdAt > maxAgeMs) {
+            continue;
+        }
+        results.push({ key, checkpoint });
+    }
+    return results;
+}
+/**
+ * Get aggregated cache statistics.
+ *
+ * Provides a summary of all cached proposals, timelock operations, and elections
+ * without making any RPC calls. Useful for dashboards and status displays.
+ *
+ * @param cache - Cache adapter to query
+ * @param maxErrorCount - Items with this many or more errors are counted as "errored" (default: 5)
+ */
+async function getStats(cache, maxErrorCount = 5) {
+    const checkpoints = await getAllCheckpoints(cache);
+    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) {
+        const completedStages = checkpoint.cachedData?.completedStages ?? [];
+        const isComplete = completedStages.length > 0 && (0, base_1.areAllStagesComplete)(completedStages);
+        const errorCount = checkpoint.metadata?.errorCount ?? 0;
+        const isErrored = errorCount >= maxErrorCount;
+        const inputType = checkpoint.input.type;
+        if (inputType === "governor") {
+            if (checkpoint.input.governorAddress &&
+                (0, constants_1.isElectionGovernor)(checkpoint.input.governorAddress)) {
+                electionTotal++;
+                if (isComplete)
+                    electionComplete++;
+            }
+            else {
+                proposalTotal++;
+                if (isComplete)
+                    proposalComplete++;
+                else if (isErrored)
+                    proposalErrored++;
+                else
+                    proposalActive++;
+            }
+        }
+        else if (inputType === "timelock") {
+            timelockTotal++;
+            if (isComplete)
+                timelockComplete++;
+            else if (isErrored)
+                timelockErrored++;
+            else
+                timelockActive++;
+        }
+    }
+    return {
+        total: checkpoints.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=query.js.map

package/dist/tracker/query.js.map

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

package/dist/tracker/state.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 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)
+ */
+import { TrackingCheckpoint, DiscoveryWatermarks, CacheAdapter } from "../types";
+/**
+ * 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.
+ */
+export declare class FileCache implements CacheAdapter {
+    private readonly path;
+    private cache;
+    private writeQueue;
+    constructor(path: string);
+    private load;
+    private persistSync;
+    private persist;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    keys(): IterableIterator<string>;
+}
+/**
+ * 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:"),
+ * });
+ * ```
+ */
+export declare class LocalStorageCache implements CacheAdapter {
+    private readonly prefix;
+    constructor(prefix?: string);
+    private fullKey;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    keys(prefix?: string): Promise<string[]>;
+}
+/**
+ * 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(),
+ * });
+ * ```
+ */
+export declare class MemoryCache implements CacheAdapter {
+    private cache;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    keys(): IterableIterator<string>;
+}
+/**
+ * Generate cache key from transaction hash (primary cache key format)
+ */
+export declare function txHashCacheKey(txHash: string): string;
+/**
+ * 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
+ */
+export declare function readCacheStatus(cachePath: string): Promise<{
+    watermarks: DiscoveryWatermarks;
+    checkpoints: Map<string, TrackingCheckpoint>;
+}>;
+//# sourceMappingURL=state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/tracker/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGjF;;;;GAIG;AACH,qBAAa,SAAU,YAAW,YAAY;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,UAAU,CAAoC;gBAE1C,IAAI,EAAE,MAAM;IAKxB,OAAO,CAAC,IAAI;IASZ,OAAO,CAAC,WAAW;YAKL,OAAO;IAiBf,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAItC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxC,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;CAGjC;AA2BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,GAAE,MAAmB;IAIvC,OAAO,CAAC,OAAO;IAIT,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAYtC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAatB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMlC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAe/C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAY,YAAW,YAAY;IAC9C,OAAO,CAAC,KAAK,CAAmC;IAE1C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAItC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxC,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;CAGjC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAChE,UAAU,EAAE,mBAAmB,CAAC;IAChC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC9C,CAAC,CAqBD"}