@xdc.org/interaction-detector 1.0.0 → 1.0.6

package/README.md

@@ -17,9 +17,12 @@ Combines: **events** + **direct calls** + **internal calls** + **transaction tra
     - [1. ContractWatcher — Real-Time Monitoring](#1-contractwatcher--real-time-monitoring)
     - [2. BlockScanner — Historical Queries](#2-blockscanner--historical-queries)
     - [3. TransactionTracer — Deep Transaction Analysis](#3-transactiontracer--deep-transaction-analysis)
+  - [LogPoller — Standalone Log Fetching](#logpoller--standalone-log-fetching)
   - [Explorer API Client](#explorer-api-client)
   - [Event Decoder \& ABI Registry](#event-decoder--abi-registry)
   - [Checkpoint Persistence](#checkpoint-persistence)
+    - [Built-in Backends](#built-in-backends)
+    - [Custom Backends](#custom-backends)
   - [Utility Functions](#utility-functions)
   - [Configuration Reference](#configuration-reference)
     - [InteractionDetectorConfig (ContractWatcher)](#interactiondetectorconfig-contractwatcher)
@@ -51,17 +54,17 @@ Combines: **events** + **direct calls** + **internal calls** + **transaction tra
 ## Installation
 
 ```bash
-npm install xdc-interaction-detector
+npm install @xdc.org/interaction-detector
 ```
 
-**Dependencies:** `ethers` v6, `axios`, `ws` — all installed automatically.
+**Dependencies:** `ethers` v6, `ws` — all installed automatically. HTTP calls use Node.js native `fetch` (requires Node ≥ 18).
 
 ---
 
 ## Quick Start
 
 ```typescript
-import { ContractWatcher } from 'xdc-interaction-detector';
+import { ContractWatcher } from '@xdc.org/interaction-detector';
 
 const watcher = new ContractWatcher({
   // RPC endpoints
@@ -80,8 +83,9 @@ const watcher = new ContractWatcher({
 
   // Explorer API — enables direct & internal call detection
   explorer: {
-    apiUrl: 'https://xdc.blocksscan.io/api',
-    apiKey: 'YOUR_API_KEY', // optional — higher rate limits
+    apiUrl: 'https://api.etherscan.io/v2/api',
+    apiKey: 'YOUR_ETHERSCAN_API_KEY', // optional — higher rate limits
+    chainId: 50, // XDC Mainnet
     rateLimitPerSec: 5,
   },
 
@@ -120,7 +124,7 @@ Watches one or more contract addresses for all interactions in real-time using t
 **Creating a watcher:**
 
 ```typescript
-import { ContractWatcher } from 'xdc-interaction-detector';
+import { ContractWatcher } from '@xdc.org/interaction-detector';
 
 const watcher = new ContractWatcher({
   // ─── Required ───────────────────────────────────────────
@@ -141,9 +145,9 @@ const watcher = new ContractWatcher({
 
   // ─── Optional: Explorer API (direct + internal calls) ───
   explorer: {
-    apiUrl: 'https://xdc.blocksscan.io/api',
-    apiKey: 'YOUR_XDCSCAN_API_KEY',       // optional — get higher rate limits
-    chainId: 50,                           // required for Etherscan v2
+    apiUrl: 'https://api.etherscan.io/v2/api', // Etherscan v2 supports XDC
+    apiKey: 'YOUR_ETHERSCAN_API_KEY',      // optional — get higher rate limits
+    chainId: 50,                           // XDC Mainnet (required for Etherscan v2)
     rateLimitPerSec: 5,                    // default: 5 req/s
     pollIntervalMs: 60_000,               // how often to check explorer (default: 60s)
   },
@@ -254,7 +258,7 @@ Scans a block range for all events and interactions involving a contract. Automa
 **Scanning for events:**
 
 ```typescript
-import { BlockScanner } from 'xdc-interaction-detector';
+import { BlockScanner } from '@xdc.org/interaction-detector';
 
 const scanner = new BlockScanner({
   rpcUrl: 'https://rpc.xinfin.network',
@@ -264,8 +268,9 @@ const scanner = new BlockScanner({
 
   // Optional: explorer for direct + internal tx enrichment
   explorer: {
-    apiUrl: 'https://xdc.blocksscan.io/api',
-    apiKey: 'YOUR_API_KEY',
+    apiUrl: 'https://api.etherscan.io/v2/api',
+    apiKey: 'YOUR_ETHERSCAN_API_KEY',
+    chainId: 50,
   },
 });
 
@@ -324,7 +329,7 @@ Traces a single transaction to extract the full execution story: call tree, stat
 **Full trace:**
 
 ```typescript
-import { TransactionTracer } from 'xdc-interaction-detector';
+import { TransactionTracer } from '@xdc.org/interaction-detector';
 
 const tracer = new TransactionTracer({
   rpcUrl: 'https://archive-rpc.xinfin.network', // must support debug_traceTransaction
@@ -398,7 +403,7 @@ const { stateDiffs, balanceChanges } = await tracer.traceStateDiffs('0xTxHash');
 **Call tree utilities:**
 
 ```typescript
-import { flattenCallTree, findCallsTo, extractInvolvedContracts } from 'xdc-interaction-detector';
+import { flattenCallTree, findCallsTo, extractInvolvedContracts } from '@xdc.org/interaction-detector';
 
 // Flatten the nested tree into a linear array
 const allCalls = flattenCallTree(result.callTree);
@@ -413,19 +418,67 @@ const addresses = extractInvolvedContracts(result.callTree);
 
 ---
 
+## LogPoller — Standalone Log Fetching
+
+The `LogPoller` is used internally by `ContractWatcher` and `BlockScanner`, but is also exported for standalone use when you need direct control over `eth_getLogs` fetching with automatic chunking and concurrency.
+
+```typescript
+import { LogPoller, RpcClient } from '@xdc.org/interaction-detector';
+import type { FetchLogsResult } from '@xdc.org/interaction-detector';
+
+const rpc = new RpcClient('https://rpc.xinfin.network');
+const poller = new LogPoller(
+  rpc,
+  ['0x0000000000000000000000000000000000000088'], // addresses to monitor
+  { maxBlockRange: 100, concurrency: 3 }, // optional PollingConfig
+  'info', // optional log level
+);
+
+// ── Basic usage — returns RawLog[] ──────────────────────────
+const logs = await poller.fetchLogs(75_000_000, 75_001_000);
+console.log(`Fetched ${logs.length} logs`);
+
+// ── With failure tracking — returns FetchLogsResult ─────────
+// Tracks which block ranges failed, so you can retry or alert
+const result: FetchLogsResult = await poller.fetchLogs(75_000_000, 75_001_000, { trackFailures: true });
+
+console.log(`Fetched ${result.logs.length} logs`);
+if (result.failedRanges.length > 0) {
+  console.warn('Some ranges failed:');
+  for (const range of result.failedRanges) {
+    console.warn(`  blocks ${range.from}–${range.to}: ${range.error}`);
+  }
+}
+```
+
+**`FetchLogsResult` type:**
+
+```typescript
+interface FetchLogsResult {
+  /** Successfully fetched logs */
+  logs: RawLog[];
+  /** Block ranges that failed to fetch (data may be missing for these ranges) */
+  failedRanges: Array<{ from: number; to: number; error: string }>;
+}
+```
+
+> **Note:** The default `fetchLogs(from, to)` call (without `{ trackFailures: true }`) returns `RawLog[]` directly for backward compatibility. Failed chunks return empty arrays silently — use the `trackFailures` option when you need visibility into partial failures.
+
+---
+
 ## Explorer API Client
 
 Standalone Etherscan-compatible API client. Works with XDCScan, Etherscan v2, BSCScan, PolygonScan, and any Etherscan-compatible explorer.
 
 ```typescript
-import { ExplorerClient } from 'xdc-interaction-detector';
+import { ExplorerClient } from '@xdc.org/interaction-detector';
 
 const explorer = new ExplorerClient({
-  apiUrl: 'https://xdc.blocksscan.io/api', // XDCScan
-  // apiUrl: 'https://api.etherscan.io/v2/api', // Etherscan v2 (80+ chains)
-  // apiUrl: 'https://api.bscscan.com/api',     // BSCScan
-  apiKey: 'YOUR_API_KEY', // optional — higher rate limits
-  chainId: 50, // required for Etherscan v2
+  apiUrl: 'https://api.etherscan.io/v2/api', // Etherscan v2 — supports XDC + 80 chains
+  // apiUrl: 'https://xdc.blocksscan.io/api', // XDCScan (alternative)
+  // apiUrl: 'https://api.bscscan.com/api',   // BSCScan
+  apiKey: 'YOUR_ETHERSCAN_API_KEY', // optional — higher rate limits
+  chainId: 50, // XDC Mainnet (required for Etherscan v2)
   rateLimitPerSec: 5, // built-in token-bucket rate limiter
 });
 ```
@@ -480,13 +533,13 @@ explorer.destroy(); // Cleans up rate limiter timers
 
 **Explorer compatibility:**
 
-| Explorer         | Base URL                          | Chain                    | Free Rate Limit |
-| ---------------- | --------------------------------- | ------------------------ | --------------- |
-| **XDCScan**      | `https://xdc.blocksscan.io/api`   | XDC Mainnet (50)         | 5 req/s         |
-| **Etherscan v2** | `https://api.etherscan.io/v2/api` | 80+ chains via `chainId` | 5 req/s         |
-| **BSCScan**      | `https://api.bscscan.com/api`     | BSC (56)                 | 5 req/s         |
-| **PolygonScan**  | `https://api.polygonscan.com/api` | Polygon (137)            | 5 req/s         |
-| **Custom**       | Any Etherscan-compatible URL      | Any EVM chain            | Configurable    |
+| Explorer            | Base URL                          | Chain                            | Free Rate Limit |
+| ------------------- | --------------------------------- | -------------------------------- | --------------- |
+| **Etherscan v2** ⭐ | `https://api.etherscan.io/v2/api` | XDC (50) + 80 chains via chainId | 5 req/s         |
+| **XDCScan**         | `https://xdc.blocksscan.io/api`   | XDC Mainnet (50)                 | 5 req/s         |
+| **BSCScan**         | `https://api.bscscan.com/api`     | BSC (56)                         | 5 req/s         |
+| **PolygonScan**     | `https://api.polygonscan.com/api` | Polygon (137)                    | 5 req/s         |
+| **Custom**          | Any Etherscan-compatible URL      | Any EVM chain                    | Configurable    |
 
 ---
 
@@ -495,7 +548,7 @@ explorer.destroy(); // Cleans up rate limiter timers
 The decoder handles both standard Solidity ABI encoding and XDC's non-standard encoding (where all params are packed into the `data` field).
 
 ```typescript
-import { AbiRegistry, EventDecoder } from 'xdc-interaction-detector';
+import { AbiRegistry, EventDecoder } from '@xdc.org/interaction-detector';
 
 // ── Register ABIs ────────────────────────────────────────────
 const registry = new AbiRegistry();
@@ -513,8 +566,12 @@ registry.register(
 // Register from a JSON ABI array
 registry.register('0xAnotherContract', require('./MyContract.json').abi, 'MyContract');
 
-// Auto-fetch from block explorer (verified contracts only)
-const explorer = new ExplorerClient({ apiUrl: 'https://xdc.blocksscan.io/api' });
+// Auto-fetch from block explorer (verified contracts only, requires API key)
+const explorer = new ExplorerClient({
+  apiUrl: 'https://api.etherscan.io/v2/api',
+  apiKey: 'YOUR_ETHERSCAN_API_KEY',
+  chainId: 50,
+});
 const success = await registry.registerFromExplorer('0xVerifiedContract', explorer, 'VerifiedToken');
 console.log(success ? 'ABI fetched!' : 'Contract not verified');
 
@@ -542,36 +599,112 @@ if (decoded) {
 
 Checkpoints let the watcher resume from where it left off after a restart.
 
+| Backend  | Storage                          | Survives Restart? | Best For                       |
+| -------- | -------------------------------- | ----------------- | ------------------------------ |
+| `memory` | JavaScript `Map` in RAM          | ❌ No             | Development, testing           |
+| `file`   | `checkpoints.json` on disk       | ✅ Yes            | Simple production deployments  |
+| `custom` | Your own (Redis, SQL, InfluxDB…) | ✅ Yes            | Distributed / production-grade |
+
+### Built-in Backends
+
 ```typescript
-import { MemoryCheckpoint, FileCheckpoint, createCheckpointBackend } from 'xdc-interaction-detector';
+import { MemoryCheckpoint, FileCheckpoint, createCheckpointBackend } from '@xdc.org/interaction-detector';
 
 // ── Memory (development / testing) ───────────────────────────
+// Stores in RAM only — lost when process stops
 const memCp = new MemoryCheckpoint();
 await memCp.save('watcher-key', 75_000_000);
 await memCp.load('watcher-key'); // 75000000
 
 // ── File (simple production) ─────────────────────────────────
+// Auto-creates directory and file on first save
 const fileCp = new FileCheckpoint('./checkpoints');
 await fileCp.save('watcher-key', 75_000_000);
-// Persists to ./checkpoints/checkpoints.json
+// Persists to ./checkpoints/checkpoints.json (relative to process.cwd())
 // Survives process restarts
 
-// ── Custom backend (bring your own) ──────────────────────────
-const customCp = {
-  async save(key: string, blockNumber: number) {
-    await redis.set(`checkpoint:${key}`, blockNumber);
+// ── Factory function ─────────────────────────────────────────
+const cp = createCheckpointBackend({ backend: 'file', path: './data' });
+const cp2 = createCheckpointBackend({ backend: 'memory' });
+```
+
+### Custom Backends
+
+Implement the `CheckpointBackend` interface — just two methods:
+
+```typescript
+interface CheckpointBackend {
+  save(key: string, blockNumber: number): Promise<void>;
+  load(key: string): Promise<number | null>;
+}
+```
+
+**Redis:**
+
+```typescript
+checkpoint: {
+  backend: 'custom',
+  custom: {
+    async save(key: string, blockNumber: number) {
+      await redis.set(`checkpoint:${key}`, blockNumber);
+    },
+    async load(key: string) {
+      const val = await redis.get(`checkpoint:${key}`);
+      return val ? parseInt(val) : null;
+    },
   },
-  async load(key: string) {
-    const val = await redis.get(`checkpoint:${key}`);
-    return val ? parseInt(val) : null;
+},
+```
+
+**PostgreSQL / MySQL:**
+
+```typescript
+checkpoint: {
+  backend: 'custom',
+  custom: {
+    async save(key: string, blockNumber: number) {
+      await pool.query(
+        `INSERT INTO checkpoints (key, block_number) VALUES ($1, $2)
+         ON CONFLICT (key) DO UPDATE SET block_number = $2`,
+        [key, blockNumber],
+      );
+    },
+    async load(key: string) {
+      const result = await pool.query(
+        'SELECT block_number FROM checkpoints WHERE key = $1',
+        [key],
+      );
+      return result.rows[0]?.block_number ?? null;
+    },
   },
-};
+},
+```
 
-// ── Factory function ─────────────────────────────────────────
-const cp = createCheckpointBackend({ backend: 'file', path: './data' });
-const cp2 = createCheckpointBackend({ backend: 'custom', custom: customCp });
+**InfluxDB:**
+
+```typescript
+checkpoint: {
+  backend: 'custom',
+  custom: {
+    async save(key: string, blockNumber: number) {
+      await influx.writePoints([{
+        measurement: 'checkpoints',
+        tags: { key },
+        fields: { block_number: blockNumber },
+      }]);
+    },
+    async load(key: string) {
+      const result = await influx.query(
+        `SELECT LAST(block_number) FROM checkpoints WHERE key = '${key}'`,
+      );
+      return result[0]?.block_number ?? null;
+    },
+  },
+},
 ```
 
+> **Recommendation:** Use **Redis** or **SQL** for checkpoint storage. InfluxDB is better suited for storing the detected events/interactions as time-series data rather than simple key-value checkpoint state.
+
 ---
 
 ## Utility Functions
@@ -585,9 +718,9 @@ import {
   isAddress, // validate hex address (20 bytes)
   addressEqual, // compare addresses (case-insensitive, prefix-aware)
 
-  // Formatting
+  // Formatting (precision-safe for large BigInt values)
   formatXDC, // bigint wei → '1.23M XDC' / '456.78K XDC'
-  formatWei, // bigint wei → '1.23M' (generic, no unit)
+  formatWei, // bigint wei → '1.23M' (generic, configurable decimals)
   parseHexOrDecimal, // '0x100' → 256, '256' → 256
   toHex, // 256 → '0x100'
   shortAddress, // '0x1234...abcd'
@@ -595,9 +728,21 @@ import {
 
   // Logger
   Logger, // new Logger('MyModule', 'info')
-} from 'xdc-interaction-detector';
+} from '@xdc.org/interaction-detector';
+```
+
+**Address normalization behavior:**
+
+```typescript
+normalizeAddress('0xAbCdEf...'); // → '0xabcdef...' (lowercased)
+normalizeAddress('xdcAbCdEf...'); // → '0xabcdef...' (xdc → 0x)
+normalizeAddress(''); // → '0x0000000000000000000000000000000000000000' (zero address)
 ```
 
+> **Note:** `normalizeAddress` returns the zero address for empty or falsy inputs, consistent with EVM conventions. This prevents empty strings from propagating as ghost entries in maps and sets.
+
+**Formatting precision:** Both `formatXDC` and `formatWei` use bigint arithmetic internally, so large amounts (beyond JavaScript's `Number.MAX_SAFE_INTEGER`) are displayed correctly without loss of precision.
+
 ---
 
 ## Configuration Reference
@@ -670,30 +815,33 @@ import {
 
 - **Block range limit:** XDC RPC limits `eth_getLogs` to 100 blocks per request. The `LogPoller` and `BlockScanner` automatically chunk requests. Don't set `maxBlockRange` above 100 for XDC.
 
-- **Address prefix:** XDC uses the `xdc` prefix instead of `0x`. All library functions accept both formats. Internally, everything normalizes to lowercase `0x`.
+- **Address prefix:** XDC uses the `xdc` prefix instead of `0x`. All library functions accept both formats. Internally, everything normalizes to lowercase `0x`. Empty/falsy inputs normalize to the zero address (`0x000...000`).
 
 - **Tracing:** `debug_traceTransaction` requires an archive node for historical transactions. For monitoring current blocks in real-time, a standard full node works fine.
 
+- **Atomic checkpoints:** The `FileCheckpoint` backend uses atomic write-then-rename to prevent data corruption on process crash. Checkpoint data is always consistent.
+
 ---
 
 ## Architecture
 
 ```
 ┌──────────────────────────────────────────────────────────┐
-│              xdc-interaction-detector                    │
+│            @xdc.org/interaction-detector                 │
 │                                                          │
 │  ┌───────────────────────────────────────────────────┐   │
 │  │  ContractWatcher         (real-time monitoring)   │   │
 │  │    ├── WsManager         (WebSocket subscription) │   │
-│  │    ├── LogPoller         (eth_getLogs fallback)   │   │
-│  │    ├── ExplorerClient    (txlist + txlistinternal)│   │
+│  │    ├── LogPoller*        (eth_getLogs fallback)   │   │
+│  │    ├── ExplorerClient*   (txlist + txlistinternal)│   │
 │  │    ├── EventDecoder      (ABI + XDC fallback)     │   │
 │  │    └── Checkpoint        (pluggable persistence)  │   │
 │  └───────────────────────────────────────────────────┘   │
 │                                                          │
 │  ┌────────────────────────────────────────────────────┐  │
 │  │  BlockScanner            (historical queries)      │  │
-│  │    └── ExplorerClient    (API adapter)             │  │
+│  │    ├── LogPoller*        (chunked eth_getLogs)     │  │
+│  │    └── ExplorerClient*   (API adapter)             │  │
 │  └────────────────────────────────────────────────────┘  │
 │                                                          │
 │  ┌────────────────────────────────────────────────────┐  │
@@ -707,6 +855,8 @@ import {
 │  │  (retry, timeout,  │  │  (address normalize,      │   │
 │  │   fallback, WS)    │  │   format, logger, cache)  │   │
 │  └────────────────────┘  └───────────────────────────┘   │
+│                                                          │
+│  * = also exported as standalone classes                 │
 └──────────────────────────────────────────────────────────┘
 ```
 
@@ -755,7 +905,7 @@ npm install
 # Compile TypeScript
 npm run build
 
-# Run unit tests (23 tests)
+# Run unit tests (114 tests across 11 test files)
 npm test
 
 # Watch mode (auto-recompile on save)

package/dist/checkpoint/checkpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../src/checkpoint/checkpoint.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D;;GAEG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IACxD,OAAO,CAAC,KAAK,CAAkC;IAEzC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAGhD;AAED;;;GAGG;AACH,qBAAa,cAAe,YAAW,iBAAiB;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,OAAO,GAAE,MAAwB;IAOvC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;YAKjC,QAAQ;CASvB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,CAAC,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAAE,GACtE,iBAAiB,CAanB"}
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../src/checkpoint/checkpoint.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D;;GAEG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IACxD,OAAO,CAAC,KAAK,CAAkC;IAEzC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAGhD;AAED;;;GAGG;AACH,qBAAa,cAAe,YAAW,iBAAiB;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,OAAO,GAAE,MAAwB;IAOvC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;YAKjC,QAAQ;CAWvB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B,GAAG,iBAAiB,CAapB"}

package/dist/checkpoint/checkpoint.js

@@ -30,7 +30,9 @@ export class FileCheckpoint {
     async save(key, blockNumber) {
         const data = await this.readFile();
         data[key] = blockNumber;
-        fs.writeFileSync(this.filePath, JSON.stringify(data, null, 2));
+        const tmpPath = this.filePath + '.tmp';
+        fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+        fs.renameSync(tmpPath, this.filePath);
     }
     async load(key) {
         const data = await this.readFile();
@@ -43,7 +45,9 @@ export class FileCheckpoint {
                 return JSON.parse(content);
             }
         }
-        catch { /* ignore corrupt file */ }
+        catch {
+            /* ignore corrupt file */
+        }
         return {};
     }
 }

package/dist/checkpoint/checkpoint.js.map

@@ -1 +1 @@
-{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../../src/checkpoint/checkpoint.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAG7B;;GAEG;AACH,MAAM,OAAO,gBAAgB;IACnB,KAAK,GAAwB,IAAI,GAAG,EAAE,CAAC;IAE/C,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,WAAmB;QACzC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IACrC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,cAAc;IACR,QAAQ,CAAS;IAElC,YAAY,UAAkB,eAAe;QAC3C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,WAAmB;QACzC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnC,IAAI,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC;QACxB,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACjE,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IAC3B,CAAC;IAEO,KAAK,CAAC,QAAQ;QACpB,IAAI,CAAC;YACH,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACjC,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;gBACxD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;QACrC,OAAO,EAAE,CAAC;IACZ,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAuE;IAEvE,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,gBAAgB,EAAE,CAAC;IAE3C,QAAQ,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,KAAK,MAAM;YACT,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACzC,KAAK,QAAQ;YACX,IAAI,CAAC,MAAM,CAAC,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;YAC9E,OAAO,MAAM,CAAC,MAAM,CAAC;QACvB,KAAK,QAAQ,CAAC;QACd;YACE,OAAO,IAAI,gBAAgB,EAAE,CAAC;IAClC,CAAC;AACH,CAAC"}
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../../src/checkpoint/checkpoint.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAG7B;;GAEG;AACH,MAAM,OAAO,gBAAgB;IACnB,KAAK,GAAwB,IAAI,GAAG,EAAE,CAAC;IAE/C,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,WAAmB;QACzC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IACrC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,cAAc;IACR,QAAQ,CAAS;IAElC,YAAY,UAAkB,eAAe;QAC3C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,WAAmB;QACzC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnC,IAAI,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC;QACxB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC;QACvC,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACzD,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IAC3B,CAAC;IAEO,KAAK,CAAC,QAAQ;QACpB,IAAI,CAAC;YACH,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACjC,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;gBACxD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,yBAAyB;QAC3B,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAIvC;IACC,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,gBAAgB,EAAE,CAAC;IAE3C,QAAQ,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,KAAK,MAAM;YACT,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACzC,KAAK,QAAQ;YACX,IAAI,CAAC,MAAM,CAAC,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;YAC9E,OAAO,MAAM,CAAC,MAAM,CAAC;QACvB,KAAK,QAAQ,CAAC;QACd;YACE,OAAO,IAAI,gBAAgB,EAAE,CAAC;IAClC,CAAC;AACH,CAAC"}

package/dist/explorer/explorer-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explorer-client.d.ts","sourceRoot":"","sources":["../../src/explorer/explorer-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEvF,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;gBAE9B,MAAM,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,QAAQ;IAQvD;;OAEG;IACG,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,GAC1E,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAcjC;;OAEG;IACG,uBAAuB,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,GAC1E,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAcjC;;OAEG;IACG,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAWjF;;OAEG;IACG,OAAO,CACX,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAClE,OAAO,CAAC,GAAG,EAAE,CAAC;IAgBjB;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;IAmB5D;;OAEG;IACG,iBAAiB,CACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,GAC1E,OAAO,CAAC,GAAG,EAAE,CAAC;IAajB;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUlD;;OAEG;IACH,OAAO,IAAI,IAAI;YAMD,OAAO;CAoCtB"}
+{"version":3,"file":"explorer-client.d.ts","sourceRoot":"","sources":["../../src/explorer/explorer-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEvF,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;gBAE9B,MAAM,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,QAAQ;IAevD;;OAEG;IACG,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,GAC1E,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAcjC;;OAEG;IACG,uBAAuB,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,GAC1E,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAcjC;;OAEG;IACG,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAWjF;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAgBnH;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;IAmB5D;;OAEG;IACG,iBAAiB,CACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,GAC1E,OAAO,CAAC,GAAG,EAAE,CAAC;IAajB;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUlD;;OAEG;IACH,OAAO,IAAI,IAAI;YAMD,OAAO;CA0CtB"}

package/dist/explorer/explorer-client.js

@@ -4,7 +4,6 @@
  * Works with: XDCScan, Etherscan v2, BSCScan, PolygonScan, and any
  * Etherscan-compatible API by changing the base URL.
  */
-import axios from 'axios';
 import { Logger } from '../utils/logger.js';
 import { RateLimiter } from './rate-limiter.js';
 export class ExplorerClient {
@@ -19,6 +18,10 @@ export class ExplorerClient {
         this.chainId = config.chainId;
         this.rateLimiter = new RateLimiter(config.rateLimitPerSec ?? 5);
         this.logger = new Logger('ExplorerClient', logLevel ?? 'info');
+        // Warn if using Etherscan v2 without an API key (required for all endpoints)
+        if (this.baseUrl.includes('etherscan.io') && !this.apiKey) {
+            this.logger.warn('Etherscan v2 requires an API key. Requests will fail without one. Get a free key at https://etherscan.io/myapikey');
+        }
     }
     /**
      * Get external transactions for an address (txlist).
@@ -33,7 +36,7 @@ export class ExplorerClient {
             sort: options?.sort ?? 'asc',
         };
         const results = await this.request(params);
-        return (results ?? []).map((tx) => ({ ...tx, txType: 'external' }));
+        return (results ?? []).map(tx => ({ ...tx, txType: 'external' }));
     }
     /**
      * Get internal transactions for an address (txlistinternal).
@@ -48,7 +51,7 @@ export class ExplorerClient {
             sort: options?.sort ?? 'asc',
         };
         const results = await this.request(params);
-        return (results ?? []).map((tx) => ({ ...tx, txType: 'internal' }));
+        return (results ?? []).map(tx => ({ ...tx, txType: 'internal' }));
     }
     /**
      * Get internal transactions within a specific transaction (txlistinternal by txhash).
@@ -60,7 +63,7 @@ export class ExplorerClient {
             txhash: txHash,
         };
         const results = await this.request(params);
-        return (results ?? []).map((tx) => ({ ...tx, txType: 'internal' }));
+        return (results ?? []).map(tx => ({ ...tx, txType: 'internal' }));
     }
     /**
      * Get event logs for an address (getLogs).
@@ -140,17 +143,23 @@ export class ExplorerClient {
             params.chainid = String(this.chainId);
         }
         try {
-            const response = await axios.get(this.baseUrl, {
-                params,
-                timeout: 15000,
+            const queryString = new URLSearchParams(params).toString();
+            const url = `${this.baseUrl}?${queryString}`;
+            const response = await fetch(url, {
+                method: 'GET',
+                signal: AbortSignal.timeout(15000),
             });
-            const data = response.data;
-            if (data.status === '0' && data.message === 'No transactions found') {
-                return [];
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
             }
-            if (data.status === '0' && data.message !== 'No transactions found') {
-                const msg = data.result || data.message || 'Unknown error';
-                this.logger.warn(`Explorer API error: ${msg}`);
+            const data = (await response.json());
+            if (data.status === '0') {
+                const msg = (data.message || '').toLowerCase();
+                if (msg.includes('no') && (msg.includes('found') || msg.includes('record') || msg.includes('transaction'))) {
+                    return [];
+                }
+                const errorMsg = data.result || data.message || 'Unknown error';
+                this.logger.warn(`Explorer API error: ${errorMsg}`);
                 return null;
             }
             return data.result;

package/dist/explorer/explorer-client.js.map

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

package/dist/explorer/rate-limiter.d.ts

@@ -10,22 +10,34 @@ export declare class RateLimiter {
     private queue;
     private drainTimer;
     /**
+     * Initializes the rate limiter with a given requests-per-second cap.
      * @param maxPerSecond Maximum requests per second (default: 5)
      */
     constructor(maxPerSecond?: number);
     /**
-     * Acquire a token. Resolves when a request slot is available.
+     * Waits until a request slot is available, then consumes one token.
+     * If no tokens are available, the caller is queued and resolved later.
      */
     acquire(): Promise<void>;
     /**
-     * Get the number of queued requests waiting.
+     * Returns how many requests are currently waiting in the queue.
      */
     get pending(): number;
     /**
-     * Destroy the rate limiter and clear timers.
+     * Cleans up the rate limiter by clearing the drain timer
+     * and resolving all queued requests so nothing is left hanging.
      */
     destroy(): void;
+    /**
+     * Refills tokens based on elapsed time since the last refill,
+     * capping at the maximum bucket size.
+     */
     private refill;
+    /**
+     * Starts a periodic timer that refills tokens and resolves
+     * queued requests as slots become available. Stops automatically
+     * when the queue is empty.
+     */
     private startDrain;
 }
 //# sourceMappingURL=rate-limiter.d.ts.map

package/dist/explorer/rate-limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/explorer/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,UAAU,CAA+B;IAEjD;;OAEG;gBACS,YAAY,GAAE,MAAU;IAOpC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAe9B;;OAEG;IACH,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;OAEG;IACH,OAAO,IAAI,IAAI;IAWf,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,UAAU;CAkBnB"}
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/explorer/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,UAAU,CAA+B;IAEjD;;;OAGG;gBACS,YAAY,GAAE,MAAU;IAOpC;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAe9B;;OAEG;IACH,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;OAGG;IACH,OAAO,IAAI,IAAI;IAWf;;;OAGG;IACH,OAAO,CAAC,MAAM;IAQd;;;;OAIG;IACH,OAAO,CAAC,UAAU;CAkBnB"}