@gzeoneth/gov-tracker 0.4.0 → 0.5.0

package/dist/deduplication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deduplication.d.ts","sourceRoot":"","sources":["../src/deduplication.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAyB3E;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAI1E;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAG1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE,CAElF;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAY3F;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC,CAYnB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,gBAAgB,EAAE,MAAM,CAAC;IACzB,mCAAmC;IACnC,eAAe,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,CAAC;IACzB,+BAA+B;IAC/B,WAAW,EAAE;QACX,uCAAuC;QACvC,aAAa,EAAE,MAAM,CAAC;QACtB,gDAAgD;QAChD,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAoC5F;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,kBAAkB,EAAE,kBAAkB,EACtC,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB;AAED;;;;;;;GAOG;AACH,wBAAsB,2BAA2B,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CA0BtF"}
+{"version":3,"file":"deduplication.d.ts","sourceRoot":"","sources":["../src/deduplication.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAoC3E;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAI1E;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAG1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE,CAElF;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAQ3F;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC,CAKnB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,gBAAgB,EAAE,MAAM,CAAC;IACzB,mCAAmC;IACnC,eAAe,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,CAAC;IACzB,+BAA+B;IAC/B,WAAW,EAAE;QACX,uCAAuC;QACvC,aAAa,EAAE,MAAM,CAAC;QACtB,gDAAgD;QAChD,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsB5F;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,kBAAkB,EAAE,kBAAkB,EACtC,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoCxB;AAED;;;;;;;GAOG;AACH,wBAAsB,2BAA2B,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBtF"}

package/dist/deduplication.js

@@ -55,6 +55,13 @@ async function getCacheKeysAsync(cache) {
     }
     return [];
 }
+/** Load all checkpoints matching an optional key filter */
+async function loadCheckpoints(cache, keyFilter) {
+    const allKeys = await getCacheKeysAsync(cache);
+    const keys = keyFilter ? allKeys.filter(keyFilter) : allKeys;
+    const checkpoints = await Promise.all(keys.map((key) => cache.get(key)));
+    return keys.map((key, i) => ({ key, checkpoint: checkpoints[i] ?? null }));
+}
 /**
  * Check if a timelock operation calldata involves Security Council management
  *
@@ -130,13 +137,12 @@ function filterChildCheckpoints(results) {
  * @returns Map of child key to parent key
  */
 async function getChildToParentMap(cache) {
+    const entries = await loadCheckpoints(cache);
     const result = new Map();
-    const keys = await getCacheKeysAsync(cache);
-    for (const key of keys) {
-        const checkpoint = await cache.get(key);
-        if (checkpoint?.metadata?.sourceCheckpoint) {
-            result.set(key, checkpoint.metadata.sourceCheckpoint);
-        }
+    for (const { key, checkpoint } of entries) {
+        const source = checkpoint?.metadata?.sourceCheckpoint;
+        if (source)
+            result.set(key, source);
     }
     return result;
 }
@@ -148,15 +154,10 @@ async function getChildToParentMap(cache) {
  * @returns Array of child checkpoint keys
  */
 async function getChildCheckpoints(parentKey, cache) {
-    const children = [];
-    const keys = await getCacheKeysAsync(cache);
-    for (const key of keys) {
-        const checkpoint = await cache.get(key);
-        if (checkpoint?.metadata?.sourceCheckpoint === parentKey) {
-            children.push(key);
-        }
-    }
-    return children;
+    const entries = await loadCheckpoints(cache);
+    return entries
+        .filter(({ checkpoint }) => checkpoint?.metadata?.sourceCheckpoint === parentKey)
+        .map(({ key }) => key);
 }
 /**
  * Get deduplication statistics for the cache
@@ -165,36 +166,25 @@ async function getChildCheckpoints(parentKey, cache) {
  * @returns Statistics about checkpoint relationships
  */
 async function getDeduplicationStats(cache) {
-    const keys = await getCacheKeysAsync(cache);
-    let totalCheckpoints = 0;
+    const entries = await loadCheckpoints(cache, (key) => key !== "discovery:watermarks");
     let childCheckpoints = 0;
     let fromElections = 0;
     let fromProposals = 0;
-    for (const key of keys) {
-        // Skip watermarks
-        if (key === "discovery:watermarks")
-            continue;
-        totalCheckpoints++;
-        const checkpoint = await cache.get(key);
+    for (const { checkpoint } of entries) {
         const source = checkpoint?.metadata?.sourceCheckpoint;
         if (source) {
             childCheckpoints++;
-            if (source.startsWith("election:")) {
+            if (source.startsWith("election:"))
                 fromElections++;
-            }
-            else {
+            else
                 fromProposals++;
-            }
         }
     }
     return {
-        totalCheckpoints,
-        rootCheckpoints: totalCheckpoints - childCheckpoints,
+        totalCheckpoints: entries.length,
+        rootCheckpoints: entries.length - childCheckpoints,
         childCheckpoints,
-        parentTypes: {
-            fromElections,
-            fromProposals,
-        },
+        parentTypes: { fromElections, fromProposals },
     };
 }
 /**
@@ -215,17 +205,17 @@ async function findPotentialParent(timelockCheckpoint, cache) {
     const isL2ConstitutionalTimelock = timelockAddr === constants_1.ADDRESSES.L2_CONSTITUTIONAL_TIMELOCK?.toLowerCase();
     if (isL2ConstitutionalTimelock) {
         // Search completed elections that might have created this
-        for (const key of keys) {
-            if (!key.startsWith("election:"))
-                continue;
-            const electionCheckpoint = await cache.get(key);
+        const electionKeys = keys.filter((key) => key.startsWith("election:"));
+        const electionCheckpoints = await Promise.all(electionKeys.map((key) => cache.get(key)));
+        for (let i = 0; i < electionKeys.length; i++) {
+            const electionCheckpoint = electionCheckpoints[i];
             const status = electionCheckpoint?.cachedData?.electionStatus;
             // Completed elections with executed member proposals create timelock ops
             if (status?.phase === "COMPLETED" && status.memberProposalId) {
                 // This election completed and may have created this timelock op
                 // Without more detailed tracking of the execution tx, we can't be 100% sure
                 // but this is a reasonable heuristic
-                return key;
+                return electionKeys[i];
             }
         }
     }
@@ -243,24 +233,14 @@ async function findPotentialParent(timelockCheckpoint, cache) {
  * @returns Number of newly linked checkpoints
  */
 async function autoLinkOrphanedCheckpoints(cache) {
-    const keys = await getCacheKeysAsync(cache);
+    const entries = await loadCheckpoints(cache, (key) => key.startsWith("tx:"));
+    const orphaned = entries.filter(({ checkpoint }) => checkpoint && !checkpoint.metadata?.sourceCheckpoint && checkpoint.input.type === "timelock");
+    const parentResults = await Promise.all(orphaned.map(({ checkpoint }) => findPotentialParent(checkpoint, cache)));
     let linkedCount = 0;
-    for (const key of keys) {
-        if (!key.startsWith("tx:"))
-            continue;
-        const checkpoint = await cache.get(key);
-        if (!checkpoint)
-            continue;
-        // Skip if already linked
-        if (checkpoint.metadata?.sourceCheckpoint)
-            continue;
-        // Skip if not a timelock checkpoint
-        if (checkpoint.input.type !== "timelock")
-            continue;
-        // Try to find a parent
-        const parentKey = await findPotentialParent(checkpoint, cache);
+    for (let i = 0; i < orphaned.length; i++) {
+        const parentKey = parentResults[i];
         if (parentKey) {
-            await linkCheckpointToChild(key, parentKey, cache);
+            await linkCheckpointToChild(orphaned[i].key, parentKey, cache);
             linkedCount++;
         }
     }

package/dist/deduplication.js.map

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

package/dist/delegates/cache.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Delegate cache loading, validation, and query helpers
+ *
+ * All functions are synchronous and operate on a loaded DelegateCache.
+ * No RPC calls — pure data access.
+ */
+import type { DelegateCache, DelegateCacheStats, DelegateInfo } from "../types/delegates";
+export declare const DELEGATE_CACHE_VERSION = 1;
+export declare function serializeDelegateCache(cache: DelegateCache): Record<string, unknown>;
+/**
+ * Get the path to the bundled delegate cache shipped with the package.
+ * Tries multiple candidate paths to support dist/ and src/ layouts.
+ */
+export declare function getBundledDelegateCachePath(): string | undefined;
+/**
+ * Load the bundled delegate cache shipped with the package.
+ * Returns the parsed DelegateCache object.
+ */
+export declare function loadBundledDelegateCache(): DelegateCache;
+/** Extract the delegates array from a cache */
+export declare function extractDelegates(cache: DelegateCache): DelegateInfo[];
+/** Extract display statistics from a cache */
+export declare function getDelegateCacheStats(cache: DelegateCache): DelegateCacheStats;
+/** Get top N delegates by voting power (already sorted in cache) */
+export declare function getTopDelegates(cache: DelegateCache, limit?: number): DelegateInfo[];
+/**
+ * Look up a delegate's rank and cached voting power.
+ * Returns undefined if address not found.
+ * Uses pre-computed Map for O(1) lookup.
+ */
+export declare function getDelegateRankInfo(cache: DelegateCache, address: `0x${string}` | string): {
+    rank: number;
+    votingPower: string;
+} | undefined;
+/** Filter delegates by minimum voting power threshold (wei) */
+export declare function filterDelegatesByMinPower(delegates: DelegateInfo[], minVotingPower: string): DelegateInfo[];
+/** Filter delegates by address substring match (case-insensitive) */
+export declare function filterDelegatesByAddress(delegates: DelegateInfo[], addressFilter: string): DelegateInfo[];
+/**
+ * Runtime validation that an unknown value is a valid DelegateCache.
+ * Expects compact delegate keys ({a, vp, b}) and expands them in-place.
+ */
+export declare function validateDelegateCache(data: unknown): data is DelegateCache;
+//# sourceMappingURL=cache.d.ts.map

package/dist/delegates/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/delegates/cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE1F,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAYxC,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYpF;AAcD;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,GAAG,SAAS,CAWhE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,aAAa,CAWxD;AAED,+CAA+C;AAC/C,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,EAAE,CAErE;AAED,8CAA8C;AAC9C,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,kBAAkB,CAQ9E;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CAKpF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,KAAK,MAAM,EAAE,GAAG,MAAM,GAC9B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAMnD;AAED,+DAA+D;AAC/D,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,YAAY,EAAE,EACzB,cAAc,EAAE,MAAM,GACrB,YAAY,EAAE,CAGhB;AAED,qEAAqE;AACrE,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,YAAY,EAAE,EACzB,aAAa,EAAE,MAAM,GACpB,YAAY,EAAE,CAGhB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,aAAa,CA2B1E"}

package/dist/delegates/cache.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * Delegate cache loading, validation, and query helpers
+ *
+ * All functions are synchronous and operate on a loaded DelegateCache.
+ * No RPC calls — pure data access.
+ */
+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.DELEGATE_CACHE_VERSION = void 0;
+exports.serializeDelegateCache = serializeDelegateCache;
+exports.getBundledDelegateCachePath = getBundledDelegateCachePath;
+exports.loadBundledDelegateCache = loadBundledDelegateCache;
+exports.extractDelegates = extractDelegates;
+exports.getDelegateCacheStats = getDelegateCacheStats;
+exports.getTopDelegates = getTopDelegates;
+exports.getDelegateRankInfo = getDelegateRankInfo;
+exports.filterDelegatesByMinPower = filterDelegatesByMinPower;
+exports.filterDelegatesByAddress = filterDelegatesByAddress;
+exports.validateDelegateCache = validateDelegateCache;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const ethers_1 = require("ethers");
+const sanitize_1 = require("../utils/sanitize");
+exports.DELEGATE_CACHE_VERSION = 1;
+const rankLookupCache = new WeakMap();
+function serializeDelegate(d) {
+    return { a: d.address, vp: d.votingPower, b: d.lastChangeBlock };
+}
+function deserializeDelegate(d) {
+    return { address: d.a, votingPower: d.vp, lastChangeBlock: d.b };
+}
+function serializeDelegateCache(cache) {
+    return {
+        version: exports.DELEGATE_CACHE_VERSION,
+        generatedAt: cache.generatedAt,
+        snapshotBlock: cache.snapshotBlock,
+        startBlock: cache.startBlock,
+        chainId: cache.chainId,
+        totalVotingPower: cache.totalVotingPower,
+        totalSupply: cache.totalSupply,
+        delegates: cache.delegates.map(serializeDelegate),
+        stats: cache.stats,
+    };
+}
+function getRankMap(cache) {
+    let map = rankLookupCache.get(cache);
+    if (!map) {
+        map = new Map();
+        for (let i = 0; i < cache.delegates.length; i++) {
+            map.set(cache.delegates[i].address.toLowerCase(), i);
+        }
+        rankLookupCache.set(cache, map);
+    }
+    return map;
+}
+/**
+ * Get the path to the bundled delegate cache shipped with the package.
+ * Tries multiple candidate paths to support dist/ and src/ layouts.
+ */
+function getBundledDelegateCachePath() {
+    const candidates = [
+        path.join(__dirname, "..", "data", "delegate-cache.json"), // dist/delegates -> dist/data
+        path.join(__dirname, "..", "..", "data", "delegate-cache.json"), // src/delegates -> data (dev)
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Load the bundled delegate cache shipped with the package.
+ * Returns the parsed DelegateCache object.
+ */
+function loadBundledDelegateCache() {
+    const cachePath = getBundledDelegateCachePath();
+    if (!cachePath) {
+        throw new Error("Delegate cache not found. Run 'yarn cache:delegates' to generate it.");
+    }
+    const raw = fs.readFileSync(cachePath, "utf8");
+    const data = (0, sanitize_1.safeJsonParse)(raw);
+    if (!data || !validateDelegateCache(data)) {
+        throw new Error("Invalid delegate cache format at " + cachePath);
+    }
+    return data;
+}
+/** Extract the delegates array from a cache */
+function extractDelegates(cache) {
+    return cache.delegates;
+}
+/** Extract display statistics from a cache */
+function getDelegateCacheStats(cache) {
+    return {
+        totalDelegates: cache.stats.totalDelegates,
+        snapshotBlock: cache.snapshotBlock,
+        generatedAt: cache.generatedAt,
+        totalVotingPower: cache.totalVotingPower,
+        totalSupply: cache.totalSupply,
+    };
+}
+/** Get top N delegates by voting power (already sorted in cache) */
+function getTopDelegates(cache, limit) {
+    if (limit === undefined || limit >= cache.delegates.length) {
+        return cache.delegates;
+    }
+    return cache.delegates.slice(0, limit);
+}
+/**
+ * Look up a delegate's rank and cached voting power.
+ * Returns undefined if address not found.
+ * Uses pre-computed Map for O(1) lookup.
+ */
+function getDelegateRankInfo(cache, address) {
+    const map = getRankMap(cache);
+    const index = map.get(address.toLowerCase());
+    if (index === undefined)
+        return undefined;
+    const delegate = cache.delegates[index];
+    return { rank: index + 1, votingPower: delegate.votingPower };
+}
+/** Filter delegates by minimum voting power threshold (wei) */
+function filterDelegatesByMinPower(delegates, minVotingPower) {
+    const threshold = ethers_1.ethers.BigNumber.from(minVotingPower);
+    return delegates.filter((d) => ethers_1.ethers.BigNumber.from(d.votingPower).gte(threshold));
+}
+/** Filter delegates by address substring match (case-insensitive) */
+function filterDelegatesByAddress(delegates, addressFilter) {
+    const lower = addressFilter.toLowerCase();
+    return delegates.filter((d) => d.address.toLowerCase().includes(lower));
+}
+/**
+ * Runtime validation that an unknown value is a valid DelegateCache.
+ * Expects compact delegate keys ({a, vp, b}) and expands them in-place.
+ */
+function validateDelegateCache(data) {
+    if (data === null || typeof data !== "object")
+        return false;
+    const obj = data;
+    if (typeof obj.version !== "number")
+        return false;
+    if (typeof obj.generatedAt !== "string")
+        return false;
+    if (typeof obj.snapshotBlock !== "number")
+        return false;
+    if (typeof obj.startBlock !== "number")
+        return false;
+    if (typeof obj.chainId !== "number")
+        return false;
+    if (typeof obj.totalVotingPower !== "string")
+        return false;
+    if (typeof obj.totalSupply !== "string")
+        return false;
+    if (!Array.isArray(obj.delegates))
+        return false;
+    const stats = obj.stats;
+    if (stats === null || typeof stats !== "object")
+        return false;
+    if (typeof stats.totalDelegates !== "number")
+        return false;
+    if (obj.delegates.length > 0) {
+        const first = obj.delegates[0];
+        if (typeof first.a !== "string" || typeof first.vp !== "string" || typeof first.b !== "number")
+            return false;
+        obj.delegates = obj.delegates.map(deserializeDelegate);
+    }
+    return true;
+}
+//# sourceMappingURL=cache.js.map

package/dist/delegates/cache.js.map

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

package/dist/delegates/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Delegate Indexing & Query Module
+ *
+ * Provides delegate voting power caching, lookup, and live queries
+ * for Arbitrum governance token delegates.
+ */
+export { loadBundledDelegateCache, getBundledDelegateCachePath, extractDelegates, getDelegateCacheStats, validateDelegateCache, serializeDelegateCache, DELEGATE_CACHE_VERSION, } from "./cache";
+export { getTopDelegates, getDelegateRankInfo, filterDelegatesByMinPower, filterDelegatesByAddress, } from "./cache";
+export { queryDelegatesNotVoted, queryDelegateVotingPowers } from "./queries";
+export type { QueryDelegatesNotVotedOptions } from "./queries";
+export { buildDelegateCache } from "./indexer";
+export type { BuildDelegateCacheOptions } from "./indexer";
+//# sourceMappingURL=index.d.ts.map

package/dist/delegates/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/delegates/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAC9E,YAAY,EAAE,6BAA6B,EAAE,MAAM,WAAW,CAAC;AAG/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,YAAY,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC"}

package/dist/delegates/index.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Delegate Indexing & Query Module
+ *
+ * Provides delegate voting power caching, lookup, and live queries
+ * for Arbitrum governance token delegates.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDelegateCache = exports.queryDelegateVotingPowers = exports.queryDelegatesNotVoted = exports.filterDelegatesByAddress = exports.filterDelegatesByMinPower = exports.getDelegateRankInfo = exports.getTopDelegates = exports.DELEGATE_CACHE_VERSION = exports.serializeDelegateCache = exports.validateDelegateCache = exports.getDelegateCacheStats = exports.extractDelegates = exports.getBundledDelegateCachePath = exports.loadBundledDelegateCache = void 0;
+// Cache access (sync, no RPC)
+var cache_1 = require("./cache");
+Object.defineProperty(exports, "loadBundledDelegateCache", { enumerable: true, get: function () { return cache_1.loadBundledDelegateCache; } });
+Object.defineProperty(exports, "getBundledDelegateCachePath", { enumerable: true, get: function () { return cache_1.getBundledDelegateCachePath; } });
+Object.defineProperty(exports, "extractDelegates", { enumerable: true, get: function () { return cache_1.extractDelegates; } });
+Object.defineProperty(exports, "getDelegateCacheStats", { enumerable: true, get: function () { return cache_1.getDelegateCacheStats; } });
+Object.defineProperty(exports, "validateDelegateCache", { enumerable: true, get: function () { return cache_1.validateDelegateCache; } });
+Object.defineProperty(exports, "serializeDelegateCache", { enumerable: true, get: function () { return cache_1.serializeDelegateCache; } });
+Object.defineProperty(exports, "DELEGATE_CACHE_VERSION", { enumerable: true, get: function () { return cache_1.DELEGATE_CACHE_VERSION; } });
+// Query helpers (sync, operate on loaded cache)
+var cache_2 = require("./cache");
+Object.defineProperty(exports, "getTopDelegates", { enumerable: true, get: function () { return cache_2.getTopDelegates; } });
+Object.defineProperty(exports, "getDelegateRankInfo", { enumerable: true, get: function () { return cache_2.getDelegateRankInfo; } });
+Object.defineProperty(exports, "filterDelegatesByMinPower", { enumerable: true, get: function () { return cache_2.filterDelegatesByMinPower; } });
+Object.defineProperty(exports, "filterDelegatesByAddress", { enumerable: true, get: function () { return cache_2.filterDelegatesByAddress; } });
+// Live queries (requires provider)
+var queries_1 = require("./queries");
+Object.defineProperty(exports, "queryDelegatesNotVoted", { enumerable: true, get: function () { return queries_1.queryDelegatesNotVoted; } });
+Object.defineProperty(exports, "queryDelegateVotingPowers", { enumerable: true, get: function () { return queries_1.queryDelegateVotingPowers; } });
+// Indexer
+var indexer_1 = require("./indexer");
+Object.defineProperty(exports, "buildDelegateCache", { enumerable: true, get: function () { return indexer_1.buildDelegateCache; } });
+//# sourceMappingURL=index.js.map

package/dist/delegates/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/delegates/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,8BAA8B;AAC9B,iCAQiB;AAPf,iHAAA,wBAAwB,OAAA;AACxB,oHAAA,2BAA2B,OAAA;AAC3B,yGAAA,gBAAgB,OAAA;AAChB,8GAAA,qBAAqB,OAAA;AACrB,8GAAA,qBAAqB,OAAA;AACrB,+GAAA,sBAAsB,OAAA;AACtB,+GAAA,sBAAsB,OAAA;AAGxB,gDAAgD;AAChD,iCAKiB;AAJf,wGAAA,eAAe,OAAA;AACf,4GAAA,mBAAmB,OAAA;AACnB,kHAAA,yBAAyB,OAAA;AACzB,iHAAA,wBAAwB,OAAA;AAG1B,mCAAmC;AACnC,qCAA8E;AAArE,iHAAA,sBAAsB,OAAA;AAAE,oHAAA,yBAAyB,OAAA;AAG1D,UAAU;AACV,qCAA+C;AAAtC,6GAAA,kBAAkB,OAAA"}

package/dist/delegates/indexer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Delegate cache indexer
+ *
+ * Scans DelegateVotesChanged events from the ARB token contract
+ * and produces a DelegateCache snapshot.
+ *
+ * Uses adaptive chunking to handle event-dense periods (e.g., ARB airdrop)
+ * where even moderate block ranges exceed RPC log limits.
+ *
+ * Processes events into a Map per-chunk to avoid OOM on full genesis builds
+ * (~millions of events over 370M+ blocks).
+ */
+import { ethers } from "ethers";
+import type { DelegateCache } from "../types/delegates";
+export interface BuildDelegateCacheOptions {
+    existingCache?: DelegateCache;
+    force?: boolean;
+    startBlock?: number;
+    /** Minimum voting power in wei (default: 10 ARB) */
+    minVotingPower?: string;
+    /** Token contract address (default: ADDRESSES.ARB_TOKEN) */
+    tokenAddress?: string;
+    onProgress?: (pct: number, block: number) => void;
+}
+/**
+ * Build or incrementally update a delegate voting power cache.
+ *
+ * Scans DelegateVotesChanged events and aggregates the latest
+ * voting power per delegate address.
+ */
+export declare function buildDelegateCache(provider: ethers.providers.Provider, options?: BuildDelegateCacheOptions): Promise<DelegateCache>;
+//# sourceMappingURL=indexer.d.ts.map

package/dist/delegates/indexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../../src/delegates/indexer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,oBAAoB,CAAC;AAsBtE,MAAM,WAAW,yBAAyB;IACxC,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnD;AAqGD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACnC,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,aAAa,CAAC,CAoGxB"}