@gzeoneth/gov-tracker 0.1.0

package/dist/utils/timing.js

@@ -0,0 +1,303 @@
+"use strict";
+/**
+ * Timing utilities for ETA calculations
+ *
+ * Handles block-based timing across L1 and L2
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateTimestampFromBlock = estimateTimestampFromBlock;
+exports.calculateEta = calculateEta;
+exports.calculateRemainingSeconds = calculateRemainingSeconds;
+exports.getCurrentBlockInfo = getCurrentBlockInfo;
+exports.getL1BlockNumberFromL2 = getL1BlockNumberFromL2;
+exports.getL1BlockForL2Block = getL1BlockForL2Block;
+exports.getFirstL2BlockForL1Block = getFirstL2BlockForL1Block;
+exports.blockAfterDelay = blockAfterDelay;
+exports.calculateExpectedEta = calculateExpectedEta;
+const ethers_1 = require("ethers");
+const lib_1 = require("@arbitrum/sdk/dist/lib/utils/lib");
+const constants_1 = require("../constants");
+const rpc_utils_1 = require("./rpc-utils");
+const logger_1 = require("./logger");
+const log = logger_1.loggers.rpc;
+/**
+ * Get the completion timestamp from a stage's transactions.
+ *
+ * For stages with multiple transactions (e.g., timelock stages with both
+ * "queued" and "executed" txs), this finds the tx with description "executed"
+ * or falls back to the last transaction in the array.
+ */
+function getCompletionTimestamp(stage) {
+    if (!stage.transactions?.length)
+        return undefined;
+    // Find tx with description "executed", or use last tx
+    const execTx = stage.transactions.find((tx) => tx.description === "executed") ??
+        stage.transactions[stage.transactions.length - 1];
+    return execTx?.timestamp;
+}
+/**
+ * Convert block number to estimated timestamp
+ */
+function estimateTimestampFromBlock(blockNumber, currentBlock, currentTimestamp, blockTime = constants_1.BLOCK_TIMES.L2) {
+    const blockDiff = blockNumber - currentBlock;
+    const timeDiff = blockDiff * blockTime;
+    return Math.floor(currentTimestamp + timeDiff);
+}
+/**
+ * Calculate ETA for a future block
+ */
+function calculateEta(targetBlock, currentBlock, currentTimestamp, blockTime = constants_1.BLOCK_TIMES.L2) {
+    if (targetBlock <= currentBlock) {
+        return null; // Already passed
+    }
+    return estimateTimestampFromBlock(targetBlock, currentBlock, currentTimestamp, blockTime);
+}
+/**
+ * Calculate remaining time in seconds
+ */
+function calculateRemainingSeconds(targetBlock, currentBlock, blockTime = constants_1.BLOCK_TIMES.L2) {
+    const blockDiff = targetBlock - currentBlock;
+    if (blockDiff <= 0) {
+        return 0;
+    }
+    return Math.floor(blockDiff * blockTime);
+}
+// Short-lived cache for getCurrentBlockInfo (2 seconds TTL)
+// Uses WeakMap to avoid memory leaks when providers are garbage collected
+const blockInfoCache = new WeakMap();
+const BLOCK_INFO_CACHE_TTL_MS = 2000; // 2 seconds - short enough for L2's fast blocks
+/**
+ * Get current block info from a provider
+ *
+ * Results are cached for 2 seconds to reduce redundant RPC calls during a single
+ * tracking operation. The cache is per-provider.
+ */
+async function getCurrentBlockInfo(provider) {
+    const cached = blockInfoCache.get(provider);
+    const now = Date.now();
+    if (cached && now - cached.fetchedAt < BLOCK_INFO_CACHE_TTL_MS) {
+        log("getBlock(latest): block=%d (cached)", cached.blockNumber);
+        return { blockNumber: cached.blockNumber, timestamp: cached.timestamp };
+    }
+    const start = now;
+    const block = await (0, rpc_utils_1.queryWithRetry)(() => provider.getBlock("latest"));
+    log("getBlock(latest): block=%d (%dms)", block.number, Date.now() - start);
+    const result = {
+        blockNumber: block.number,
+        timestamp: block.timestamp,
+        fetchedAt: now,
+    };
+    blockInfoCache.set(provider, result);
+    return { blockNumber: result.blockNumber, timestamp: result.timestamp };
+}
+/**
+ * Get current L1 block number as seen from L2
+ *
+ * Arbitrum L2 blocks include the L1 block number in their metadata.
+ * This returns the L1 block number from the latest L2 block.
+ *
+ * IMPORTANT: This returns the actual L1 block number, not the L2 block number.
+ * Use this for comparing against vetting deadlines which are in L1 blocks.
+ */
+async function getL1BlockNumberFromL2(l2Provider) {
+    const jsonRpcProvider = l2Provider;
+    if (typeof jsonRpcProvider.send !== "function") {
+        throw new Error("Provider does not support direct RPC calls (send method required)");
+    }
+    const start = Date.now();
+    const rawBlock = await (0, rpc_utils_1.queryWithRetry)(() => jsonRpcProvider.send("eth_getBlockByNumber", ["latest", false]));
+    if (!rawBlock || !rawBlock.l1BlockNumber) {
+        throw new Error("Could not get L1 block number from latest L2 block");
+    }
+    const l1Block = ethers_1.BigNumber.from(rawBlock.l1BlockNumber);
+    log("getL1BlockNumberFromL2: l1Block=%s (%dms)", l1Block.toString(), Date.now() - start);
+    return l1Block;
+}
+/**
+ * Get the corresponding L1 block number for an L2 block.
+ *
+ * Arbitrum L2 blocks include the L1 block number at the time they were created.
+ * This is exposed via the `l1BlockNumber` field in the raw block data.
+ *
+ * This is useful for determining search ranges when looking for L1 events
+ * that correspond to L2 actions.
+ *
+ * Note: This relies on Arbitrum-specific block metadata and requires a
+ * JsonRpcProvider that supports the `send` method for raw RPC calls.
+ */
+async function getL1BlockForL2Block(l2Provider, l2BlockNumber) {
+    const jsonRpcProvider = l2Provider;
+    if (typeof jsonRpcProvider.send !== "function") {
+        throw new Error("Provider does not support direct RPC calls (send method required)");
+    }
+    const rawBlock = await (0, rpc_utils_1.queryWithRetry)(() => jsonRpcProvider.send("eth_getBlockByNumber", ["0x" + l2BlockNumber.toString(16), false]));
+    if (!rawBlock || !rawBlock.l1BlockNumber) {
+        throw new Error(`Could not get L1 block number for L2 block ${l2BlockNumber}`);
+    }
+    // Use BigNumber.from for consistent parsing (handles both hex and decimal)
+    // This matches getL1BlockNumberFromL2's approach
+    const l1Block = ethers_1.BigNumber.from(rawBlock.l1BlockNumber);
+    return l1Block.toNumber();
+}
+/**
+ * Get the first L2 block for a given L1 block number using Arbitrum SDK.
+ *
+ * Arbitrum governors use L1 block numbers for voting deadlines. This function
+ * finds the corresponding L2 block for searching L2 logs.
+ *
+ * Uses binary search via the SDK's getFirstBlockForL1Block which queries
+ * NodeInterface.l2BlockRangeForL1() internally.
+ *
+ * @param l2Provider - L2 provider (must be JsonRpcProvider)
+ * @param targetL1Block - Target L1 block number
+ * @param options.minL2Block - Minimum L2 block to search from (speeds up binary search)
+ * @param options.maxL2Block - Maximum L2 block to search to (speeds up binary search)
+ * @returns First L2 block for the given L1 block, or undefined if not found
+ */
+async function getFirstL2BlockForL1Block(l2Provider, targetL1Block, options = {}) {
+    const jsonRpcProvider = l2Provider;
+    const result = await (0, lib_1.getFirstBlockForL1Block)({
+        arbitrumProvider: jsonRpcProvider,
+        forL1Block: targetL1Block,
+        allowGreater: true, // Allow finding block even if L1 block is slightly in the future
+        minArbitrumBlock: options.minL2Block,
+        maxArbitrumBlock: options.maxL2Block,
+    });
+    if (result !== undefined) {
+        log("getFirstL2BlockForL1Block: L1=%d -> L2=%d (bounds: %s-%s)", targetL1Block, result, options.minL2Block ?? "start", options.maxL2Block ?? "latest");
+    }
+    return result;
+}
+/**
+ * Find a block number shortly after a delay expires.
+ *
+ * Instead of using a hardcoded block time which can overshoot or undershoot,
+ * this function checks actual block timestamps and adjusts iteratively.
+ *
+ * IMPORTANT: This function errs on the side of being EARLY rather than late.
+ * When searching for events, it's better to start searching a bit before the
+ * target time than to miss the event by starting too late.
+ *
+ * @param provider - Provider to fetch block data
+ * @param startBlock - The block number where the delay started
+ * @param delaySeconds - The delay duration in seconds
+ * @param estimatedBlockTime - Estimated seconds per block (default: 12 for L1)
+ * @returns A block number at or shortly before timestamp >= startTimestamp + delaySeconds
+ */
+async function blockAfterDelay(provider, startBlock, delaySeconds, estimatedBlockTime = constants_1.BLOCK_TIMES.L1) {
+    const start = Date.now();
+    // Get the start block timestamp
+    const startBlockData = await (0, rpc_utils_1.queryWithRetry)(() => provider.getBlock(startBlock));
+    if (!startBlockData) {
+        throw new Error(`Could not fetch block ${startBlock}`);
+    }
+    const targetTimestamp = startBlockData.timestamp + delaySeconds;
+    // Get current block for upper bound
+    const { blockNumber: currentBlock, timestamp: currentTimestamp } = await getCurrentBlockInfo(provider);
+    // If current time hasn't passed the target, return startBlock (too early to have executed)
+    if (currentTimestamp < targetTimestamp) {
+        log("blockAfterDelay: delay not yet passed, returning startBlock=%d (%dms)", startBlock, Date.now() - start);
+        return startBlock;
+    }
+    // Initial estimate
+    let resultBlock = startBlock + Math.floor(delaySeconds / estimatedBlockTime);
+    // Clamp to valid range
+    resultBlock = Math.min(resultBlock, currentBlock);
+    resultBlock = Math.max(resultBlock, startBlock + 1);
+    // Safety margin: 100 blocks on L1 (~20 min), ensures we start before target
+    const safetyMargin = 100;
+    // Iteratively refine until we're before the target timestamp
+    const maxIterations = 10;
+    for (let i = 0; i < maxIterations; i++) {
+        const block = await (0, rpc_utils_1.queryWithRetry)(() => provider.getBlock(resultBlock));
+        if (!block) {
+            log("blockAfterDelay: could not fetch block %d, using estimate", resultBlock);
+            break;
+        }
+        const diff = block.timestamp - targetTimestamp;
+        if (diff < 0) {
+            // We're before the target - perfect, this is where we want to be
+            log("blockAfterDelay: found block=%d (diff=%ds before target) in %d iterations (%dms)", resultBlock, -diff, i + 1, Date.now() - start);
+            return resultBlock;
+        }
+        // We're at or after the target - backtrack
+        // Backtrack by the overshoot amount plus safety margin
+        const blocksToBacktrack = Math.ceil(diff / estimatedBlockTime) + safetyMargin;
+        const previousBlock = resultBlock;
+        resultBlock = Math.max(startBlock + 1, resultBlock - blocksToBacktrack);
+        log("blockAfterDelay: block %d is +%ds after target, backtracking %d blocks to %d", previousBlock, diff, blocksToBacktrack, resultBlock);
+        // Prevent infinite loop if we can't go back further
+        if (resultBlock === startBlock + 1) {
+            log("blockAfterDelay: can't backtrack further, using startBlock+1=%d", resultBlock);
+            return resultBlock;
+        }
+    }
+    log("blockAfterDelay: returning block=%d after max iterations (%dms)", resultBlock, Date.now() - start);
+    return resultBlock;
+}
+// Simple ETA Calculation for Individual Stages
+/**
+ * Stage duration mapping for ETA calculations (in days)
+ */
+const STAGE_DURATION_DAYS = {
+    VOTING_ACTIVE: constants_1.GOVERNANCE_STAGE_DURATION_DAYS.VOTING,
+    L2_TIMELOCK: constants_1.GOVERNANCE_STAGE_DURATION_DAYS.L2_CONSTITUTIONAL_TIMELOCK,
+    L2_TO_L1_MESSAGE: constants_1.GOVERNANCE_STAGE_DURATION_DAYS.CHALLENGE_PERIOD,
+    L1_TIMELOCK: constants_1.GOVERNANCE_STAGE_DURATION_DAYS.L1_TIMELOCK,
+};
+/**
+ * Calculate expected ETA for a stage that hasn't started yet
+ *
+ * Estimates when a future stage will complete based on:
+ * 1. Finding a reference point (completed stage timestamp or existing ETA)
+ * 2. Calculating cumulative delays from that reference to the target stage
+ *
+ * @param stages - Array of tracked stages from a TrackingResult
+ * @param stageIndex - Index of the stage to calculate ETA for
+ * @returns Estimated completion timestamp in seconds, or undefined if cannot calculate
+ *
+ * @example
+ * ```typescript
+ * const result = await tracker.trackFromGovernor(governor, proposalId);
+ * for (let i = 0; i < result.stages.length; i++) {
+ *   const stage = result.stages[i];
+ *   if (stage.status === "NOT_STARTED") {
+ *     const eta = calculateExpectedEta(result.stages, i);
+ *     if (eta) {
+ *       console.log(`${stage.type}: Expected ~${new Date(eta * 1000).toISOString()}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+function calculateExpectedEta(stages, stageIndex) {
+    let baseEta;
+    let baseIndex = -1;
+    for (let i = stageIndex - 1; i >= 0; i--) {
+        const stage = stages[i];
+        if (stage.timing?.eta) {
+            baseEta = stage.timing.eta;
+            baseIndex = i;
+            break;
+        }
+        if (stage.status === "COMPLETED") {
+            const completionTs = getCompletionTimestamp(stage);
+            if (completionTs !== undefined) {
+                baseEta = completionTs;
+                baseIndex = i;
+                break;
+            }
+        }
+    }
+    if (baseEta === undefined) {
+        return undefined;
+    }
+    let cumulativeDelayDays = 0;
+    for (let i = baseIndex + 1; i <= stageIndex; i++) {
+        const stageType = stages[i].type;
+        cumulativeDelayDays += STAGE_DURATION_DAYS[stageType] ?? 0;
+    }
+    const delaySeconds = cumulativeDelayDays * 24 * 60 * 60;
+    return baseEta + delaySeconds;
+}
+//# sourceMappingURL=timing.js.map

package/dist/utils/timing.js.map

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

package/dist/utils/urls.d.ts

@@ -0,0 +1,20 @@
+import type { ChainType, StageTransaction } from "../types";
+/**
+ * Map ChainType to numeric chain ID
+ */
+export declare function chainTypeToId(chain: ChainType): number;
+export declare function getExplorerUrl(chainId: number, type: "tx" | "address", hash: string): string;
+export declare function getTxUrl(chainId: number, txHash: string): string;
+/**
+ * Get block explorer URL for a stage transaction
+ *
+ * @example
+ * ```typescript
+ * const stage = result.stages[0];
+ * for (const tx of stage.transactions) {
+ *   console.log(`${tx.hash}: ${getStageTransactionUrl(tx)}`);
+ * }
+ * ```
+ */
+export declare function getStageTransactionUrl(tx: StageTransaction): string;
+//# sourceMappingURL=urls.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../../src/utils/urls.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5D;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAStD;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAW5F;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,gBAAgB,GAAG,MAAM,CAGnE"}

package/dist/utils/urls.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chainTypeToId = chainTypeToId;
+exports.getExplorerUrl = getExplorerUrl;
+exports.getTxUrl = getTxUrl;
+exports.getStageTransactionUrl = getStageTransactionUrl;
+const constants_1 = require("../constants");
+/**
+ * Map ChainType to numeric chain ID
+ */
+function chainTypeToId(chain) {
+    switch (chain) {
+        case "L1":
+            return constants_1.CHAIN_IDS.ETHEREUM;
+        case "L2":
+            return constants_1.CHAIN_IDS.ARB_ONE;
+        case "NOVA":
+            return constants_1.CHAIN_IDS.NOVA;
+    }
+}
+function getExplorerUrl(chainId, type, hash) {
+    switch (chainId) {
+        case 1: // Ethereum
+            return `https://etherscan.io/${type}/${hash}`;
+        case constants_1.CHAIN_IDS.ARB_ONE:
+            return `https://arbiscan.io/${type}/${hash}`;
+        case constants_1.CHAIN_IDS.NOVA:
+            return `https://nova.arbiscan.io/${type}/${hash}`;
+        default:
+            return `https://etherscan.io/${type}/${hash}`;
+    }
+}
+function getTxUrl(chainId, txHash) {
+    return getExplorerUrl(chainId, "tx", txHash);
+}
+/**
+ * Get block explorer URL for a stage transaction
+ *
+ * @example
+ * ```typescript
+ * const stage = result.stages[0];
+ * for (const tx of stage.transactions) {
+ *   console.log(`${tx.hash}: ${getStageTransactionUrl(tx)}`);
+ * }
+ * ```
+ */
+function getStageTransactionUrl(tx) {
+    const chainId = chainTypeToId(tx.chain);
+    return getTxUrl(chainId, tx.hash);
+}
+//# sourceMappingURL=urls.js.map

package/dist/utils/urls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"urls.js","sourceRoot":"","sources":["../../src/utils/urls.ts"],"names":[],"mappings":";;AAMA,sCASC;AAED,wCAWC;AAED,4BAEC;AAaD,wDAGC;AAhDD,4CAAyC;AAGzC;;GAEG;AACH,SAAgB,aAAa,CAAC,KAAgB;IAC5C,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,IAAI;YACP,OAAO,qBAAS,CAAC,QAAQ,CAAC;QAC5B,KAAK,IAAI;YACP,OAAO,qBAAS,CAAC,OAAO,CAAC;QAC3B,KAAK,MAAM;YACT,OAAO,qBAAS,CAAC,IAAI,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,SAAgB,cAAc,CAAC,OAAe,EAAE,IAAsB,EAAE,IAAY;IAClF,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,CAAC,EAAE,WAAW;YACjB,OAAO,wBAAwB,IAAI,IAAI,IAAI,EAAE,CAAC;QAChD,KAAK,qBAAS,CAAC,OAAO;YACpB,OAAO,uBAAuB,IAAI,IAAI,IAAI,EAAE,CAAC;QAC/C,KAAK,qBAAS,CAAC,IAAI;YACjB,OAAO,4BAA4B,IAAI,IAAI,IAAI,EAAE,CAAC;QACpD;YACE,OAAO,wBAAwB,IAAI,IAAI,IAAI,EAAE,CAAC;IAClD,CAAC;AACH,CAAC;AAED,SAAgB,QAAQ,CAAC,OAAe,EAAE,MAAc;IACtD,OAAO,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,sBAAsB,CAAC,EAAoB;IACzD,MAAM,OAAO,GAAG,aAAa,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IACxC,OAAO,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@gzeoneth/gov-tracker",
+  "version": "0.1.0",
+  "description": "Lightweight, high-performance library for tracking Arbitrum DAO governance proposal lifecycle stages",
+  "license": "Apache-2.0",
+  "author": "gzeoneth",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gzeoneth/gov-tracker.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gzeoneth/gov-tracker/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "gov-tracker": "dist/cli/monitor.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "NO_RPC=1 vitest run",
+    "test:monitor": "vitest run test/monitor.test.ts",
+    "test:integration": "vitest run test/integration.test.ts test/tracker.test.ts test/retryables.test.ts",
+    "test:fork": "vitest run --config vitest.config.fork.mts",
+    "test:all": "vitest run",
+    "lint": "eslint src test --quiet",
+    "lint:fix": "eslint src test --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
+    "prepublishOnly": "yarn lint && yarn format:check && yarn build",
+    "prepare": "husky",
+    "monitor": "ts-node src/cli/monitor.ts",
+    "monitor:run": "ts-node src/cli/monitor.ts run",
+    "monitor:status": "ts-node src/cli/monitor.ts status",
+    "monitor:track": "ts-node src/cli/monitor.ts track"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  },
+  "dependencies": {
+    "@arbitrum/sdk": "^4.0.0",
+    "commander": "^14.0.2",
+    "debug": "^4.3.4",
+    "dotenv": "^17.2.3",
+    "ethers": "^5.7.2",
+    "p-limit": "3"
+  },
+  "devDependencies": {
+    "@types/debug": "^4.1.12",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.51.0",
+    "@typescript-eslint/parser": "^8.51.0",
+    "@vitest/coverage-v8": "^1.6.0",
+    "eslint": "^9.39.2",
+    "husky": "^9.1.7",
+    "jiti": "^2.6.1",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}