@gzeoneth/gov-tracker 0.4.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@
 [![codecov](https://codecov.io/gh/gzeoneth/gov-tracker/graph/badge.svg?token=2WVH8Z82TE)](https://codecov.io/gh/gzeoneth/gov-tracker)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-Track and execute Arbitrum DAO governance proposal lifecycle stages and Security Council elections.
+Track and execute Arbitrum DAO governance proposal lifecycle stages, Security Council elections, and delegate participation.
 
 ## Installation
 
@@ -15,26 +15,22 @@ yarn add @gzeoneth/gov-tracker ethers@^5.8.0
 ## Quick Start
 
 ```typescript
-import { ethers } from "ethers";
-import { createTracker, findExecutableStage, ADDRESSES } from "@gzeoneth/gov-tracker";
+import { createTracker, findExecutableStage } from "@gzeoneth/gov-tracker";
 
-// Use StaticJsonRpcProvider for better performance
+// Accepts RPC URLs directly (or ethers Provider objects)
 const tracker = createTracker({
-  l2Provider: new ethers.providers.StaticJsonRpcProvider(process.env.ARB1_RPC),
-  l1Provider: new ethers.providers.StaticJsonRpcProvider(process.env.ETH_RPC),
-  novaProvider: new ethers.providers.StaticJsonRpcProvider(process.env.NOVA_RPC),
+  l2Provider: process.env.ARB1_RPC,  // URL string or Provider
+  l1Provider: process.env.ETH_RPC,
+  novaProvider: process.env.NOVA_RPC,
   cachePath: "./gov-tracker-cache.json",
 });
 
-// Track from transaction hash
+// Track from transaction hash (auto-detects proposal type)
 const results = await tracker.trackByTxHash("0x...");
 for (const stage of results[0].stages) {
   console.log(`${stage.type}: ${stage.status}`);
 }
 
-// Or track from governor
-const result = await tracker.trackFromGovernor(ADDRESSES.CONSTITUTIONAL_GOVERNOR, proposalId);
-
 // Execute ready stages
 const readyStage = findExecutableStage(results[0].stages);
 if (readyStage) {
@@ -59,6 +55,76 @@ if (readyStage) {
 
 Statuses: `NOT_STARTED`, `PENDING`, `READY`, `COMPLETED`, `FAILED`, `SKIPPED`
 
+## Voting & Write Actions
+
+Prepare-only functions return `PreparedTransaction` objects — `{ to, data, value, chain, chainId, description }` plus optional `operationId` / `hashValidation` — and you always sign and send yourself.
+
+```typescript
+import { ethers } from "ethers";
+import {
+  prepareCastVote,
+  prepareCastVoteWithReason,
+  VOTE_SUPPORT,
+  prepareNomineeElectionVote,
+  prepareContenderRegistration,
+  NOMINEE_ELECTION_GOVERNOR_ABI,
+  ADDRESSES,
+} from "@gzeoneth/gov-tracker";
+
+// Governor proposal vote
+const tx = prepareCastVote(proposalId, VOTE_SUPPORT.FOR, "constitutional");
+await signer.sendTransaction(tx);
+
+// Vote with on-chain reason
+const tx2 = prepareCastVoteWithReason(proposalId, VOTE_SUPPORT.AGAINST, "Insufficient detail");
+
+// Security Council nominee vote (castVoteWithReasonAndParams)
+const tx3 = prepareNomineeElectionVote(proposalId, nomineeAddress, votes);
+
+// Contender registration (two-phase: sign EIP-712 typed data, then submit)
+// governorName MUST match the governor's on-chain name() value (EIP-712 domain)
+const governor = new ethers.Contract(
+  ADDRESSES.ELECTION_NOMINEE_GOVERNOR,
+  NOMINEE_ELECTION_GOVERNOR_ABI,
+  l2Provider
+);
+const governorName: string = await governor.name();
+const { typedData, buildTransaction } = prepareContenderRegistration(governorName, proposalId);
+const signature = await signer._signTypedData(typedData.domain, typedData.types, typedData.message);
+await signer.sendTransaction(buildTransaction(signature));
+```
+
+See [API Reference](./docs/API.md#governance-vote-preparation) and [Examples](./docs/EXAMPLES.md#voting) for details.
+
+## Delegates
+
+Indexed ARB delegate registry with cached voting power and live queries:
+
+```typescript
+import {
+  loadBundledDelegateCache,
+  getTopDelegates,
+  getDelegateRankInfo,
+  queryDelegatesNotVoted,
+} from "@gzeoneth/gov-tracker";
+
+// Load bundled cache (sync, no RPC)
+const cache = loadBundledDelegateCache();
+const top10 = getTopDelegates(cache, 10);
+
+// O(1) rank lookup
+const info = getDelegateRankInfo(cache, "0x1234...");
+console.log(`Rank ${info?.rank}, voting power ${info?.votingPower}`);
+
+// Live: find top delegates who haven't voted yet on an active proposal
+const notVoted = await queryDelegatesNotVoted(l2Provider, proposalId, "constitutional", {
+  limit: 10,
+  maxDelegatesToCheck: 100,
+});
+```
+
+Build or refresh the cache via CLI: `npx @gzeoneth/gov-tracker delegates`.
+
 ## CLI
 
 ```bash
@@ -97,6 +163,12 @@ npx @gzeoneth/gov-tracker ui
 
 # Track election creation tx (auto-switches to election view)
 npx @gzeoneth/gov-tracker track 0x82a0baf3...
+
+# Build or refresh delegate cache from live RPC
+npx @gzeoneth/gov-tracker delegates                          # Incremental update
+npx @gzeoneth/gov-tracker delegates --force                  # Rebuild from genesis
+npx @gzeoneth/gov-tracker delegates --min-power 1000 \
+  --output ./my-delegates.json                               # Custom filters/output
 ```
 
 **Shorthands:** `-v` (verbose), `-p` (prepare), `-w` (write), `-i` (inspect)
@@ -177,6 +249,18 @@ PRIVATE_KEY=0x...  # For execution
 
 The CLI warns when using default public RPCs. For production, set these environment variables.
 
+### RPC Provider Recommendations
+
+For reliable operation, especially during election tracking which makes many RPC calls:
+
+| Chain | Recommended Providers |
+|-------|----------------------|
+| Ethereum | [Alchemy](https://www.alchemy.com/), [Infura](https://infura.io/), [ethereum.publicnode.com](https://ethereum.publicnode.com/) |
+| Arbitrum One | [Alchemy](https://www.alchemy.com/), [arb1.arbitrum.io/rpc](https://arb1.arbitrum.io/rpc), [arbitrum.publicnode.com](https://arbitrum.publicnode.com/) |
+| Arbitrum Nova | [nova.arbitrum.io/rpc](https://nova.arbitrum.io/rpc) |
+
+**Note:** Some public RPCs like `cloudflare-eth.com` may return `-32603` internal errors during high load. If you experience intermittent failures, try switching to a dedicated provider.
+
 ## Security & Privacy
 
 **External API Lookups**: When decoding calldata, unknown function selectors are looked up via [4byte.directory](https://www.4byte.directory/). To disable: