@gzeoneth/gov-tracker 0.2.1-beta.b2eeb41 → 0.2.1-beta.e9f73a3

package/README.md

@@ -9,40 +9,30 @@ Track and execute Arbitrum DAO governance proposal lifecycle stages.
 ## Installation
 
 ```bash
-yarn add @gzeoneth/gov-tracker ethers@^5.8.0
+yarn add @gzeoneth/gov-tracker
 ```
 
 ## Quick Start
 
 ```typescript
-import { ethers } from "ethers";
-import { createTracker, findExecutableStage, ADDRESSES } from "@gzeoneth/gov-tracker";
+import { createTracker, ADDRESSES } from "@gzeoneth/gov-tracker";
 
 // Use StaticJsonRpcProvider for better performance
 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),
-  cachePath: "./gov-tracker-cache.json",
+  l2Provider: new ethers.providers.StaticJsonRpcProvider(ARB1_RPC_URL),
+  l1Provider: new ethers.providers.StaticJsonRpcProvider(ETH_RPC_URL),
+  novaProvider: new ethers.providers.StaticJsonRpcProvider(NOVA_RPC),
 });
 
-// Track from transaction hash
-const results = await tracker.trackByTxHash("0x...");
-for (const stage of results[0].stages) {
-  console.log(`${stage.type}: ${stage.status}`);
-}
-
-// Or track from governor
+// Track from governor proposal
 const result = await tracker.trackFromGovernor(ADDRESSES.CONSTITUTIONAL_GOVERNOR, proposalId);
 
-// Execute ready stages
-const readyStage = findExecutableStage(results[0].stages);
-if (readyStage) {
-  const prep = await tracker.prepareTransaction(readyStage);
-  if (prep.success) {
-    await signer.sendTransaction(prep.prepared);
-  }
+for (const stage of result.stages) {
+  console.log(`${stage.type}: ${stage.status}`);
 }
+
+// Track from transaction hash
+const results = await tracker.trackByTxHash("0x...");
 ```
 
 ## Stages
@@ -59,34 +49,89 @@ if (readyStage) {
 
 Statuses: `NOT_STARTED`, `PENDING`, `READY`, `COMPLETED`, `FAILED`, `SKIPPED`
 
+## Execution
+
+```typescript
+import { findExecutableStage } from "@gzeoneth/gov-tracker";
+
+const readyStage = findExecutableStage(result.stages);
+if (readyStage) {
+  const prepResult = await tracker.prepareTransaction(readyStage);
+  if (prepResult.success) {
+    const { to, data, value, chain } = prepResult.prepared;
+    const tx = await signer.sendTransaction({ to, data, value });
+    await tx.wait();
+  }
+}
+```
+
+## Calldata Decoding & Simulation
+
+Decode proposal calldata and prepare simulation data for Tenderly, Foundry, or other tools.
+
+```typescript
+import {
+  decodeCalldata,
+  extractAllSimulationsFromDecoded,
+  getAddressLabel
+} from "@gzeoneth/gov-tracker";
+
+// Decode proposal actions
+const stage = result.stages[0]; // PROPOSAL_CREATED
+const { calldatas, targets } = stage.data;
+
+for (let i = 0; i < calldatas.length; i++) {
+  const decoded = await decodeCalldata(calldatas[i], targets[i], 0, "arb1");
+
+  console.log(`${decoded.signature}`);
+  console.log(`Target: ${getAddressLabel(targets[i], "arb1")}`);
+
+  // Extract simulation data
+  const sims = extractAllSimulationsFromDecoded(decoded, "arb1");
+  for (const sim of sims) {
+    console.log(`Network: ${sim.simulation.networkId}`);
+    console.log(`From: ${sim.simulation.from}`);
+    console.log(`To: ${sim.simulation.to}`);
+  }
+}
+```
+
+See [Examples](./docs/EXAMPLES.md#calldata-decoding--simulation) for Tenderly and Foundry integration.
+
 ## CLI
 
 ```bash
-# Track a proposal
+# Track a proposal by transaction hash
 npx @gzeoneth/gov-tracker track 0x...
 
-# Track AND decode calldata
-npx @gzeoneth/gov-tracker track 0x... -i
+# Track AND inspect calldata (new in v0.2.1)
+npx @gzeoneth/gov-tracker track 0x... --inspect
+npx @gzeoneth/gov-tracker track 0x... -i  # shorthand
 
 # Decode calldata only (no tracking)
 npx @gzeoneth/gov-tracker track 0x... --inspect-only
 
-# Show simulation data
+# Show simulation data for Tenderly/Foundry integration
 npx @gzeoneth/gov-tracker track 0x... --show-simulation
 
-# Execute ready stages
+# Execute ready stages (with shorthands)
 npx @gzeoneth/gov-tracker track 0x... -w --private-key $PRIVATE_KEY
+npx @gzeoneth/gov-tracker track 0x... -v -p -w --private-key $PRIVATE_KEY  # verbose + prepare + write
 
 # Discover and track all proposals
 npx @gzeoneth/gov-tracker run
 
-# Disable caching
+# Disable caching (useful for one-off checks)
 npx @gzeoneth/gov-tracker track 0x... --no-cache
 ```
 
-**Shorthands:** `-v` (verbose), `-p` (prepare), `-w` (write), `-i` (inspect)
+**CLI Shorthands** (v0.2.1+):
+- `-v` for `--verbose` - Enable verbose logging
+- `-p` for `--prepare` - Prepare transactions for ready stages
+- `-w` for `--write` - Execute prepared transactions
+- `-i` for `--inspect` - Track AND decode calldata
 
-**Bundled Cache**: The CLI includes a pre-built cache of completed proposals. On first run, this eliminates initial discovery RPC calls. SDK users can access via `getBundledCachePath()` or direct JSON import - see [Examples](./docs/EXAMPLES.md#bundled-cache-bootstrap).
+**Bundled Cache**: The CLI includes a pre-built cache of completed proposals (~95 proposals). On first run, this is copied to your local cache directory, eliminating initial discovery RPC calls. SDK users can access via `getBundledCachePath()` (Node.js) or direct JSON import for bundlers - see [Bundled Cache](./docs/EXAMPLES.md#bundled-cache-bootstrap).
 
 ## Environment
 
@@ -97,23 +142,29 @@ NOVA_RPC=https://nova.arbitrum.io/rpc
 PRIVATE_KEY=0x...  # For execution
 ```
 
-The CLI warns when using default public RPCs. For production, set these environment variables.
-
 ## Security & Privacy
 
-**External API Lookups**: When decoding calldata, unknown function selectors are looked up via [4byte.directory](https://www.4byte.directory/). To disable:
+**RPC URLs**: The CLI warns when using default public RPCs. For production use, set `ETH_RPC`, `ARB1_RPC`, and `NOVA_RPC` environment variables to avoid rate limits and ensure reliability.
+
+**External API Lookups**: When decoding calldata, unknown function selectors are looked up via [4byte.directory](https://www.4byte.directory/). This sends selector hashes to an external API. To disable:
 
 ```bash
+# Via environment variable
 DISABLE_4BYTE_LOOKUP=1 npx @gzeoneth/gov-tracker track 0x...
 ```
 
 ```typescript
+// Via SDK option
 import { lookupSignature } from "@gzeoneth/gov-tracker";
+
 const result = await lookupSignature("0x12345678", { disableApiLookup: true });
 ```
 
+When disabled, only local signatures (governance-related functions) are available.
+
 ## Documentation
 
+- [Getting Started](./docs/GETTING_STARTED.md) - Installation and basic usage
 - [API Reference](./docs/API.md) - Complete API documentation
 - [Examples](./docs/EXAMPLES.md) - Common patterns and use cases
 - [Architecture](./docs/ARCHITECTURE.md) - SDK internals and design
@@ -124,10 +175,12 @@ const result = await lookupSignature("0x12345678", { disableApiLookup: true });
 yarn build              # Compile TypeScript
 yarn test               # Run fast tests (no RPC)
 yarn test:coverage      # Run tests with coverage
+yarn test:coverage:fork # Run fork tests with coverage (requires archive RPC)
+yarn test:coverage:all  # Merge all coverage reports
 yarn lint               # Run ESLint
 ```
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for development workflow.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development workflow and publishing instructions.
 
 ## Terminology
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gzeoneth/gov-tracker",
-  "version": "0.2.1-beta.b2eeb41",
+  "version": "0.2.1-beta.e9f73a3",
   "description": "Lightweight, high-performance library for tracking Arbitrum DAO governance proposal lifecycle stages",
   "license": "Apache-2.0",
   "author": "gzeoneth",