@gzeoneth/gov-tracker 0.1.0

package/dist/stages/voting.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Voting Stage Tracking
+ *
+ * Stage 2: Track voting period including extensions and vetting
+ *
+ * IMPORTANT: Vetting deadline uses L1 block numbers, not L2 block numbers.
+ * When calculating ETA for vetting period, we must use L1 block time.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackVotingStage = trackVotingStage;
+const governor_discovery_1 = require("../discovery/governor-discovery");
+const security_council_1 = require("../discovery/security-council");
+const stage_builder_1 = require("./stage-builder");
+const timing_1 = require("../utils/timing");
+const constants_1 = require("../constants");
+/**
+ * Track voting stage for a proposal
+ */
+async function trackVotingStage(governorAddress, proposalId, proposalData, provider) {
+    const builder = new stage_builder_1.StageBuilder("VOTING_ACTIVE", "L2");
+    // Get current block info
+    const { blockNumber: currentBlock, timestamp: currentTimestamp } = await (0, timing_1.getCurrentBlockInfo)(provider);
+    // Check if voting has started
+    if (proposalData.startBlock.gt(currentBlock)) {
+        // Voting not started yet
+        const remainingSeconds = (0, timing_1.calculateRemainingSeconds)(proposalData.startBlock.toNumber(), currentBlock, constants_1.BLOCK_TIMES.L2);
+        builder
+            .status("NOT_STARTED")
+            .timing({ startedAt: currentTimestamp, eta: currentTimestamp + remainingSeconds })
+            .data({
+            startBlock: proposalData.startBlock.toString(),
+            currentBlock: currentBlock.toString(),
+        });
+        return { stage: builder.build(), votingData: null };
+    }
+    // Get voting data from governor
+    const votingData = await (0, governor_discovery_1.getVotingData)(governorAddress, proposalId, provider);
+    // Check for vetting period - only Security Council governors have vetting
+    const proposalType = (0, governor_discovery_1.detectProposalType)(governorAddress);
+    const isElectionProposal = proposalType === "ELECTION_NOMINEE" || proposalType === "ELECTION_MEMBER";
+    const vettingInfo = isElectionProposal
+        ? await (0, security_council_1.checkVettingPeriod)(governorAddress, proposalId, provider)
+        : {
+            hasVettingPeriod: false,
+            vettingDeadline: null,
+            isVettingActive: false,
+            vetterAddress: null,
+        };
+    // Check if voting was extended
+    const wasExtended = votingData.extendedDeadline !== undefined &&
+        !votingData.extendedDeadline.eq(votingData.deadline);
+    const extensionPossible = !votingData.isVotingPeriodOver && !votingData.hasReachedQuorum;
+    // Add voting statistics
+    builder.data({
+        forVotes: votingData.forVotes.toString(),
+        againstVotes: votingData.againstVotes.toString(),
+        abstainVotes: votingData.abstainVotes.toString(),
+        quorum: votingData.quorum.toString(),
+        quorumReached: votingData.hasReachedQuorum,
+        deadline: votingData.deadline.toString(),
+        extendedDeadline: votingData.extendedDeadline?.toString(),
+        wasExtended,
+        extensionPossible,
+        hasVettingPeriod: vettingInfo.hasVettingPeriod,
+        vettingDeadline: vettingInfo.vettingDeadline?.toString(),
+        isVettingActive: vettingInfo.isVettingActive,
+    });
+    // Determine voting status
+    const proposalState = await (0, governor_discovery_1.getProposalState)(governorAddress, proposalId, provider);
+    builder.data({ proposalState });
+    if (proposalState === "Active") {
+        const remainingSeconds = (0, timing_1.calculateRemainingSeconds)(votingData.deadline.toNumber(), currentBlock, constants_1.BLOCK_TIMES.L2);
+        builder.status("PENDING").timing({
+            startedAt: currentTimestamp,
+            eta: currentTimestamp + remainingSeconds,
+            delaySeconds: remainingSeconds,
+        });
+    }
+    else if (proposalState === "Succeeded" ||
+        proposalState === "Queued" ||
+        proposalState === "Executed") {
+        // Check vetting period first
+        if (vettingInfo.isVettingActive && vettingInfo.vettingDeadline) {
+            const currentL1Block = await (0, timing_1.getL1BlockNumberFromL2)(provider);
+            const remainingSeconds = (0, timing_1.calculateRemainingSeconds)(vettingInfo.vettingDeadline.toNumber(), currentL1Block.toNumber(), constants_1.BLOCK_TIMES.L1);
+            builder
+                .status("PENDING")
+                .data({ waitingForVetting: true })
+                .timing({
+                eta: currentTimestamp + remainingSeconds,
+                delaySeconds: remainingSeconds,
+            });
+        }
+        else {
+            builder.status("COMPLETED");
+        }
+    }
+    else if (proposalState === "Defeated" ||
+        proposalState === "Canceled" ||
+        proposalState === "Expired") {
+        builder.status("FAILED");
+    }
+    else if (proposalState === "Pending") {
+        builder.status("NOT_STARTED");
+    }
+    return { stage: builder.build(), votingData };
+}
+//# sourceMappingURL=voting.js.map

package/dist/stages/voting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voting.js","sourceRoot":"","sources":["../../src/stages/voting.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAqBH,4CA2HC;AA5ID,wEAIyC;AACzC,oEAAmE;AACnE,mDAA+C;AAC/C,4CAIyB;AACzB,4CAA2C;AAE3C;;GAEG;AACI,KAAK,UAAU,gBAAgB,CACpC,eAAuB,EACvB,UAAkB,EAClB,YAA0B,EAC1B,QAAmC;IAKnC,MAAM,OAAO,GAAG,IAAI,4BAAY,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;IAExD,yBAAyB;IACzB,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,GAC9D,MAAM,IAAA,4BAAmB,EAAC,QAAQ,CAAC,CAAC;IAEtC,8BAA8B;IAC9B,IAAI,YAAY,CAAC,UAAU,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC;QAC7C,yBAAyB;QACzB,MAAM,gBAAgB,GAAG,IAAA,kCAAyB,EAChD,YAAY,CAAC,UAAU,CAAC,QAAQ,EAAE,EAClC,YAAY,EACZ,uBAAW,CAAC,EAAE,CACf,CAAC;QAEF,OAAO;aACJ,MAAM,CAAC,aAAa,CAAC;aACrB,MAAM,CAAC,EAAE,SAAS,EAAE,gBAAgB,EAAE,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;aACjF,IAAI,CAAC;YACJ,UAAU,EAAE,YAAY,CAAC,UAAU,CAAC,QAAQ,EAAE;YAC9C,YAAY,EAAE,YAAY,CAAC,QAAQ,EAAE;SACtC,CAAC,CAAC;QAEL,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACtD,CAAC;IAED,gCAAgC;IAChC,MAAM,UAAU,GAAG,MAAM,IAAA,kCAAa,EAAC,eAAe,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;IAE9E,0EAA0E;IAC1E,MAAM,YAAY,GAAG,IAAA,uCAAkB,EAAC,eAAe,CAAC,CAAC;IACzD,MAAM,kBAAkB,GACtB,YAAY,KAAK,kBAAkB,IAAI,YAAY,KAAK,iBAAiB,CAAC;IAE5E,MAAM,WAAW,GAAG,kBAAkB;QACpC,CAAC,CAAC,MAAM,IAAA,qCAAkB,EAAC,eAAe,EAAE,UAAU,EAAE,QAAQ,CAAC;QACjE,CAAC,CAAC;YACE,gBAAgB,EAAE,KAAK;YACvB,eAAe,EAAE,IAAI;YACrB,eAAe,EAAE,KAAK;YACtB,aAAa,EAAE,IAAI;SACpB,CAAC;IAEN,+BAA+B;IAC/B,MAAM,WAAW,GACf,UAAU,CAAC,gBAAgB,KAAK,SAAS;QACzC,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IACvD,MAAM,iBAAiB,GAAG,CAAC,UAAU,CAAC,kBAAkB,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC;IAEzF,wBAAwB;IACxB,OAAO,CAAC,IAAI,CAAC;QACX,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,QAAQ,EAAE;QACxC,YAAY,EAAE,UAAU,CAAC,YAAY,CAAC,QAAQ,EAAE;QAChD,YAAY,EAAE,UAAU,CAAC,YAAY,CAAC,QAAQ,EAAE;QAChD,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;QACpC,aAAa,EAAE,UAAU,CAAC,gBAAgB;QAC1C,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,QAAQ,EAAE;QACxC,gBAAgB,EAAE,UAAU,CAAC,gBAAgB,EAAE,QAAQ,EAAE;QACzD,WAAW;QACX,iBAAiB;QACjB,gBAAgB,EAAE,WAAW,CAAC,gBAAgB;QAC9C,eAAe,EAAE,WAAW,CAAC,eAAe,EAAE,QAAQ,EAAE;QACxD,eAAe,EAAE,WAAW,CAAC,eAAe;KAC7C,CAAC,CAAC;IAEH,0BAA0B;IAC1B,MAAM,aAAa,GAAG,MAAM,IAAA,qCAAgB,EAAC,eAAe,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;IACpF,OAAO,CAAC,IAAI,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;IAEhC,IAAI,aAAa,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,gBAAgB,GAAG,IAAA,kCAAyB,EAChD,UAAU,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAC9B,YAAY,EACZ,uBAAW,CAAC,EAAE,CACf,CAAC;QACF,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC;YAC/B,SAAS,EAAE,gBAAgB;YAC3B,GAAG,EAAE,gBAAgB,GAAG,gBAAgB;YACxC,YAAY,EAAE,gBAAgB;SAC/B,CAAC,CAAC;IACL,CAAC;SAAM,IACL,aAAa,KAAK,WAAW;QAC7B,aAAa,KAAK,QAAQ;QAC1B,aAAa,KAAK,UAAU,EAC5B,CAAC;QACD,6BAA6B;QAC7B,IAAI,WAAW,CAAC,eAAe,IAAI,WAAW,CAAC,eAAe,EAAE,CAAC;YAC/D,MAAM,cAAc,GAAG,MAAM,IAAA,+BAAsB,EAAC,QAAQ,CAAC,CAAC;YAC9D,MAAM,gBAAgB,GAAG,IAAA,kCAAyB,EAChD,WAAW,CAAC,eAAe,CAAC,QAAQ,EAAE,EACtC,cAAc,CAAC,QAAQ,EAAE,EACzB,uBAAW,CAAC,EAAE,CACf,CAAC;YACF,OAAO;iBACJ,MAAM,CAAC,SAAS,CAAC;iBACjB,IAAI,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC;iBACjC,MAAM,CAAC;gBACN,GAAG,EAAE,gBAAgB,GAAG,gBAAgB;gBACxC,YAAY,EAAE,gBAAgB;aAC/B,CAAC,CAAC;QACP,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;SAAM,IACL,aAAa,KAAK,UAAU;QAC5B,aAAa,KAAK,UAAU;QAC5B,aAAa,KAAK,SAAS,EAC3B,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC3B,CAAC;SAAM,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QACvC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAChC,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,UAAU,EAAE,CAAC;AAChD,CAAC"}

package/dist/tracker/context.d.ts

@@ -0,0 +1,111 @@
+/**
+ * TrackingContext - Functional state management for pipeline tracking
+ *
+ * This module provides a purely functional approach to tracking context:
+ * - TrackingContext interface defines the immutable state shape
+ * - Pure functions transform state and derive values
+ * - No classes, no mutation, no hidden state
+ *
+ * Benefits:
+ * - Easy testing: just create plain objects
+ * - Transparent: can log/inspect full state anytime
+ * - Predictable: same input → same output
+ * - Composable: mix and match functions freely
+ * - Debuggable: save/restore state snapshots
+ */
+import { ethers } from "ethers";
+import { TrackedStage, TrackingCheckpoint, TrackingInput, StageType, CallScheduledData, ProposalData, ProposalType, ProposalState, OnProgressCallback, ChunkingConfig } from "../types";
+/**
+ * Providers for multi-chain operations
+ */
+export interface Providers {
+    readonly l2: ethers.providers.Provider;
+    readonly l1: ethers.providers.Provider;
+    readonly nova: ethers.providers.Provider;
+}
+/**
+ * Options for creating a TrackingContext
+ */
+export interface CreateTrackingContextOptions {
+    providers: Providers;
+    input: TrackingInput;
+    onProgress?: OnProgressCallback;
+    chunkingConfig?: ChunkingConfig;
+    checkpoint?: TrackingCheckpoint;
+    cacheKey?: string;
+    /** Bootstrap data for timelock-only tracking */
+    callScheduledData?: CallScheduledData[];
+}
+/**
+ * TrackingContext - Immutable state for pipeline tracking
+ *
+ * All values are derived from stages. This interface represents
+ * a snapshot of the pipeline at a point in time.
+ *
+ * @example
+ * ```typescript
+ * let ctx = createTrackingContext({ providers, input });
+ * ctx = await addStage(ctx, proposalCreatedStage);
+ * const opId = getOperationId(ctx);
+ * ```
+ */
+export interface TrackingContext {
+    readonly providers: Providers;
+    readonly chunkingConfig: ChunkingConfig;
+    readonly onProgress?: OnProgressCallback;
+    readonly cacheKey?: string;
+    readonly input: TrackingInput;
+    readonly callScheduledData?: CallScheduledData[];
+    readonly stages: TrackedStage[];
+    readonly stageIndex: number;
+}
+/**
+ * Create a new TrackingContext.
+ */
+export declare function createTrackingContext(options: CreateTrackingContextOptions): TrackingContext;
+/**
+ * Add or update a stage. Returns new context.
+ */
+export declare function addStage(ctx: TrackingContext, stage: TrackedStage): Promise<TrackingContext>;
+/** Check if a stage is completed (COMPLETED or SKIPPED). */
+export declare function isStageCompleted(ctx: TrackingContext, type: StageType): boolean;
+/** Get a completed stage for zero-RPC resume. */
+export declare function getCompletedStage(ctx: TrackingContext, type: StageType): TrackedStage | undefined;
+/** Get a cached stage (any status). */
+export declare function getCachedStage(ctx: TrackingContext, type: StageType): TrackedStage | undefined;
+/**
+ * Check if all stages are complete.
+ */
+export declare function isComplete(ctx: TrackingContext): boolean;
+export declare const getGovernorAddress: (ctx: TrackingContext) => string | undefined;
+export declare const getProposalId: (ctx: TrackingContext) => string | undefined;
+export declare function getTimelockAddress(ctx: TrackingContext): string | undefined;
+export declare function getOperationId(ctx: TrackingContext): string | undefined;
+export declare function getCallScheduledData(ctx: TrackingContext): CallScheduledData[] | undefined;
+export declare const getFirstCallScheduledData: (ctx: TrackingContext) => CallScheduledData | undefined;
+export declare const getQueueBlockNumber: (ctx: TrackingContext) => number | undefined;
+/** Proposal data from PROPOSAL_CREATED stage */
+export declare function getProposalData(ctx: TrackingContext): ProposalData | undefined;
+export declare function getProposalType(ctx: TrackingContext): ProposalType | undefined;
+export declare const getIsElection: (ctx: TrackingContext) => boolean;
+export declare const getProposalState: (ctx: TrackingContext) => ProposalState | undefined;
+export declare function getVotingEndBlock(ctx: TrackingContext): number | undefined;
+export declare function getL2ExecutionTxHash(ctx: TrackingContext): string | undefined;
+export declare const getFirstExecutableBlock: (ctx: TrackingContext) => number | undefined;
+export declare function getOutboxExecutionTx(ctx: TrackingContext): {
+    hash: string;
+    blockNumber: number;
+} | undefined;
+export declare function getL1ExecutionTxHash(ctx: TrackingContext): string | undefined;
+export declare function createCheckpoint(ctx: TrackingContext): TrackingCheckpoint;
+export declare function toResult(ctx: TrackingContext): {
+    input: TrackingInput;
+    stages: TrackedStage[];
+    checkpoint: TrackingCheckpoint;
+    isComplete: boolean;
+    proposalType: ProposalType | undefined;
+    proposalData: ProposalData | undefined;
+    currentState: ProposalState | undefined;
+    isElection: boolean;
+};
+//# sourceMappingURL=context.d.ts.map

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

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

package/dist/tracker/context.js

@@ -0,0 +1,264 @@
+"use strict";
+/**
+ * TrackingContext - Functional state management for pipeline tracking
+ *
+ * This module provides a purely functional approach to tracking context:
+ * - TrackingContext interface defines the immutable state shape
+ * - Pure functions transform state and derive values
+ * - No classes, no mutation, no hidden state
+ *
+ * Benefits:
+ * - Easy testing: just create plain objects
+ * - Transparent: can log/inspect full state anytime
+ * - Predictable: same input → same output
+ * - Composable: mix and match functions freely
+ * - Debuggable: save/restore state snapshots
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFirstExecutableBlock = exports.getProposalState = exports.getIsElection = exports.getQueueBlockNumber = exports.getFirstCallScheduledData = exports.getProposalId = exports.getGovernorAddress = void 0;
+exports.createTrackingContext = createTrackingContext;
+exports.addStage = addStage;
+exports.isStageCompleted = isStageCompleted;
+exports.getCompletedStage = getCompletedStage;
+exports.getCachedStage = getCachedStage;
+exports.isComplete = isComplete;
+exports.getTimelockAddress = getTimelockAddress;
+exports.getOperationId = getOperationId;
+exports.getCallScheduledData = getCallScheduledData;
+exports.getProposalData = getProposalData;
+exports.getProposalType = getProposalType;
+exports.getVotingEndBlock = getVotingEndBlock;
+exports.getL2ExecutionTxHash = getL2ExecutionTxHash;
+exports.getOutboxExecutionTx = getOutboxExecutionTx;
+exports.getL1ExecutionTxHash = getL1ExecutionTxHash;
+exports.createCheckpoint = createCheckpoint;
+exports.toResult = toResult;
+const ethers_1 = require("ethers");
+const logger_1 = require("../utils/logger");
+const base_1 = require("../stages/base");
+const governor_discovery_1 = require("../discovery/governor-discovery");
+const constants_1 = require("../constants");
+const { tracker: logTracker } = logger_1.loggers;
+// State Creation
+/**
+ * Create a new TrackingContext.
+ */
+function createTrackingContext(options) {
+    // Initialize stages based on tracking path
+    const includeProposal = options.input.type === "governor";
+    const addressForPath = options.input.type === "governor"
+        ? options.input.governorAddress
+        : options.input.type === "timelock"
+            ? options.input.timelockAddress
+            : "";
+    const initialStages = (0, base_1.initializeStagesForPath)(addressForPath, includeProposal);
+    let ctx = {
+        providers: options.providers,
+        chunkingConfig: options.chunkingConfig ?? constants_1.DEFAULT_CHUNKING_CONFIG,
+        onProgress: options.onProgress,
+        cacheKey: options.cacheKey,
+        input: options.input,
+        callScheduledData: options.callScheduledData,
+        stages: initialStages,
+        stageIndex: 0,
+    };
+    // Load from checkpoint if provided
+    if (options.checkpoint?.cachedData.completedStages?.length) {
+        ctx = loadFromCheckpoint(ctx, options.checkpoint);
+    }
+    return ctx;
+}
+/**
+ * Load stages from a checkpoint.
+ */
+function loadFromCheckpoint(ctx, checkpoint) {
+    const completedStages = checkpoint.cachedData.completedStages;
+    if (!completedStages?.length)
+        return ctx;
+    logTracker("RESUME: loading %d completed stages from checkpoint", completedStages.length);
+    let stages = ctx.stages;
+    for (const stage of completedStages) {
+        stages = (0, base_1.updateStageInList)(stages, stage);
+    }
+    return { ...ctx, stages, stageIndex: completedStages.length };
+}
+// Stage Management
+/**
+ * Add or update a stage. Returns new context.
+ */
+async function addStage(ctx, stage) {
+    const newStages = (0, base_1.updateStageInList)(ctx.stages, stage);
+    const newCtx = {
+        ...ctx,
+        stages: newStages,
+        stageIndex: ctx.stageIndex + 1,
+    };
+    await emitProgress(newCtx, stage);
+    return newCtx;
+}
+// Stage lookup helper (defined early for use in stage management functions)
+const findStage = (ctx, type) => ctx.stages.find((s) => s.type === type);
+/** Check if a stage is completed (COMPLETED or SKIPPED). */
+function isStageCompleted(ctx, type) {
+    const s = findStage(ctx, type);
+    return s?.status === "COMPLETED" || s?.status === "SKIPPED";
+}
+/** Get a completed stage for zero-RPC resume. */
+function getCompletedStage(ctx, type) {
+    const s = findStage(ctx, type);
+    return s?.status === "COMPLETED" || s?.status === "SKIPPED" ? s : undefined;
+}
+/** Get a cached stage (any status). */
+function getCachedStage(ctx, type) {
+    return findStage(ctx, type);
+}
+/**
+ * Check if all stages are complete.
+ */
+function isComplete(ctx) {
+    return (0, base_1.areAllStagesComplete)(ctx.stages);
+}
+// Stage data helpers
+const stageData = (ctx, type) => findStage(ctx, type)?.data;
+const execTx = (s) => s?.transactions?.find((tx) => tx.description === "executed");
+const chainTx = (s, chain) => s?.transactions?.find((tx) => tx.chain === chain);
+// Derived Getters - Input-based
+const getGovernorAddress = (ctx) => ctx.input.type === "governor" ? ctx.input.governorAddress : undefined;
+exports.getGovernorAddress = getGovernorAddress;
+const getProposalId = (ctx) => ctx.input.type === "governor" ? ctx.input.proposalId : undefined;
+exports.getProposalId = getProposalId;
+// Derived Getters - Multi-source lookups
+function getTimelockAddress(ctx) {
+    if (ctx.input.type === "timelock")
+        return ctx.input.timelockAddress;
+    return (stageData(ctx, "PROPOSAL_QUEUED")?.timelockAddress ??
+        stageData(ctx, "L2_TIMELOCK")?.timelockAddress);
+}
+function getOperationId(ctx) {
+    if (ctx.input.type === "timelock")
+        return ctx.input.operationId;
+    return (stageData(ctx, "PROPOSAL_QUEUED")?.operationId ??
+        stageData(ctx, "L2_TIMELOCK")?.operationId);
+}
+function getCallScheduledData(ctx) {
+    if (ctx.callScheduledData)
+        return ctx.callScheduledData;
+    const qData = stageData(ctx, "PROPOSAL_QUEUED")?.callScheduledData;
+    if (qData?.length)
+        return (0, base_1.deserializeCallScheduledDataArray)(qData);
+    const l2Data = stageData(ctx, "L2_TIMELOCK")?.callScheduledData;
+    return l2Data?.length ? (0, base_1.deserializeCallScheduledDataArray)(l2Data) : undefined;
+}
+const getFirstCallScheduledData = (ctx) => getCallScheduledData(ctx)?.[0];
+exports.getFirstCallScheduledData = getFirstCallScheduledData;
+const getQueueBlockNumber = (ctx) => (0, exports.getFirstCallScheduledData)(ctx)?.blockNumber;
+exports.getQueueBlockNumber = getQueueBlockNumber;
+/** Proposal data from PROPOSAL_CREATED stage */
+function getProposalData(ctx) {
+    const s = findStage(ctx, "PROPOSAL_CREATED");
+    if (!s || s.status === "NOT_STARTED")
+        return undefined;
+    const data = s.data;
+    const tx = s.transactions?.[0];
+    if (!data.proposalId ||
+        !data.startBlock ||
+        !data.endBlock ||
+        !data.proposer ||
+        !data.targets ||
+        !data.values ||
+        !data.signatures ||
+        !data.calldatas ||
+        !tx)
+        return undefined;
+    return {
+        proposalId: data.proposalId,
+        proposer: data.proposer,
+        description: data.description,
+        targets: data.targets,
+        values: data.values.map((v) => ethers_1.BigNumber.from(v)),
+        signatures: data.signatures,
+        calldatas: data.calldatas,
+        startBlock: ethers_1.BigNumber.from(data.startBlock),
+        endBlock: ethers_1.BigNumber.from(data.endBlock),
+        creationBlock: tx.blockNumber,
+        creationTxHash: tx.hash,
+    };
+}
+function getProposalType(ctx) {
+    const data = stageData(ctx, "PROPOSAL_CREATED");
+    if (data?.proposalType)
+        return data.proposalType;
+    const addr = (0, exports.getGovernorAddress)(ctx);
+    return addr ? (0, governor_discovery_1.detectProposalType)(addr) : undefined;
+}
+const getIsElection = (ctx) => {
+    const type = getProposalType(ctx);
+    return type ? (0, governor_discovery_1.isElectionProposal)(type) : false;
+};
+exports.getIsElection = getIsElection;
+const getProposalState = (ctx) => stageData(ctx, "VOTING_ACTIVE")?.proposalState;
+exports.getProposalState = getProposalState;
+function getVotingEndBlock(ctx) {
+    const data = stageData(ctx, "VOTING_ACTIVE");
+    if (!data?.deadline)
+        return undefined;
+    const deadline = parseInt(data.deadline, 10);
+    const extended = data.extendedDeadline ? parseInt(data.extendedDeadline, 10) : 0;
+    return extended > deadline ? extended : deadline;
+}
+function getL2ExecutionTxHash(ctx) {
+    const s = findStage(ctx, "L2_TIMELOCK");
+    return s?.status === "COMPLETED" ? execTx(s)?.hash : undefined;
+}
+const getFirstExecutableBlock = (ctx) => stageData(ctx, "L2_TO_L1_MESSAGE")?.firstExecutableBlock;
+exports.getFirstExecutableBlock = getFirstExecutableBlock;
+function getOutboxExecutionTx(ctx) {
+    const s = findStage(ctx, "L2_TO_L1_MESSAGE");
+    if (s?.status !== "COMPLETED")
+        return undefined;
+    const tx = chainTx(s, "L1");
+    return tx ? { hash: tx.hash, blockNumber: tx.blockNumber } : undefined;
+}
+function getL1ExecutionTxHash(ctx) {
+    const s = findStage(ctx, "L1_TIMELOCK");
+    return s?.status === "COMPLETED" ? execTx(s)?.hash : undefined;
+}
+// Checkpoint & Result
+function createCheckpoint(ctx) {
+    const completedStages = ctx.stages.filter((s) => s.status !== "NOT_STARTED");
+    const lastProcessedStage = [...ctx.stages].reverse().find((s) => s.status !== "NOT_STARTED")?.type ?? null;
+    return {
+        version: 1,
+        createdAt: Date.now(),
+        input: ctx.input,
+        lastProcessedStage,
+        lastProcessedBlock: { l1: 0, l2: 0, nova: 0 },
+        cachedData: { completedStages },
+        metadata: { errorCount: 0, lastTrackedAt: Date.now() },
+    };
+}
+async function emitProgress(ctx, s) {
+    if (!ctx.onProgress)
+        return;
+    const idx = ctx.stages.findIndex((x) => x.type === s.type);
+    await ctx.onProgress({
+        stage: s,
+        stages: ctx.stages,
+        currentIndex: idx >= 0 ? idx : ctx.stageIndex,
+        totalStages: ctx.stages.length,
+        isComplete: isComplete(ctx),
+    });
+}
+function toResult(ctx) {
+    return {
+        input: ctx.input,
+        stages: ctx.stages,
+        checkpoint: createCheckpoint(ctx),
+        isComplete: isComplete(ctx),
+        proposalType: getProposalType(ctx),
+        proposalData: getProposalData(ctx),
+        currentState: (0, exports.getProposalState)(ctx),
+        isElection: (0, exports.getIsElection)(ctx),
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/tracker/context.js.map

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

package/dist/tracker/discovery.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Tracker Discovery Module
+ *
+ * Handles discovery of proposals and timelock operations.
+ * Provides unified discovery API with watermark management.
+ */
+import { ethers } from "ethers";
+import { DiscoveryWatermarks, DiscoveryTargets, CacheAdapter } from "../types";
+import { DiscoveredProposal } from "../discovery/governor-discovery";
+import { DiscoveredTimelockOp } from "../discovery/timelock-discovery";
+export { DiscoveredProposal, DiscoveredTimelockOp };
+/**
+ * Cache key for discovery watermarks checkpoint.
+ * Uses "discovery:" prefix to follow checkpoint pattern.
+ */
+export declare const 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.
+ */
+export declare function loadWatermarks(cache: CacheAdapter | undefined): Promise<DiscoveryWatermarks>;
+/**
+ * Save discovery watermarks to cache.
+ * Watermarks are stored as TrackingCheckpoint with proper metadata,
+ * following the same pattern as proposal/timelock checkpoints.
+ */
+export declare function saveWatermarks(watermarks: DiscoveryWatermarks, cache: CacheAdapter | undefined): 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)
+ * @param l2Provider - L2 provider
+ * @param options.chunkSize - Optional chunk size for log searches
+ * @returns Array of discovered proposals
+ */
+export declare function discoverProposals(governorAddress: string, fromBlock: number, toBlock: number, l2Provider: ethers.providers.Provider, options?: {
+    chunkSize?: 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)
+ * @param l2Provider - L2 provider
+ * @param options.chunkSize - Optional chunk size for log searches
+ * @returns Array of discovered timelock operations
+ */
+export declare function discoverTimelockOps(timelockAddress: string, fromBlock: number, toBlock: number, l2Provider: ethers.providers.Provider, options?: {
+    chunkSize?: number;
+}): Promise<DiscoveredTimelockOp[]>;
+/**
+ * Create pending checkpoints for discovered proposals.
+ * This ensures they can be retracked even if the current run times out.
+ *
+ * Note: We don't create pending checkpoints for timelock ops because:
+ * 1. Most timelock ops are tracked as part of governor proposals
+ * 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>;
+/**
+ * Discover all proposals and timelock operations with auto-watermark management.
+ *
+ * This is the unified discovery API that handles everything internally:
+ * - 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
+ *
+ * @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 options.chunkSize - Optional chunk size for log searches
+ * @returns Discovered proposals, timelock ops, and updated watermarks
+ */
+export declare function discoverAll(targets: DiscoveryTargets, toBlock: number, l2Provider: ethers.providers.Provider, cache: CacheAdapter | undefined, fromWatermarks: DiscoveryWatermarks, options?: {
+    chunkSize?: number;
+}): Promise<{
+    proposals: DiscoveredProposal[];
+    timelockOps: DiscoveredTimelockOp[];
+    watermarks: DiscoveryWatermarks;
+}>;
+//# sourceMappingURL=discovery.d.ts.map

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

@@ -0,0 +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"}