@xdc.org/interaction-detector 1.0.0 → 1.0.1

package/README.md

@@ -51,7 +51,7 @@ 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.
@@ -61,7 +61,7 @@ npm install xdc-interaction-detector
 ## Quick Start
 
 ```typescript
-import { ContractWatcher } from 'xdc-interaction-detector';
+import { ContractWatcher } from '@xdc.org/interaction-detector';
 
 const watcher = new ContractWatcher({
   // RPC endpoints
@@ -80,8 +80,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 +121,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 +142,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 +255,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 +265,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 +326,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 +400,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);
@@ -418,14 +420,14 @@ const addresses = extractInvolvedContracts(result.callTree);
 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 +482,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 +497,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();
@@ -514,7 +516,7 @@ registry.register(
 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' });
+const explorer = new ExplorerClient({ apiUrl: 'https://api.etherscan.io/v2/api', chainId: 50 });
 const success = await registry.registerFromExplorer('0xVerifiedContract', explorer, 'VerifiedToken');
 console.log(success ? 'ABI fetched!' : 'Contract not verified');
 
@@ -543,7 +545,7 @@ if (decoded) {
 Checkpoints let the watcher resume from where it left off after a restart.
 
 ```typescript
-import { MemoryCheckpoint, FileCheckpoint, createCheckpointBackend } from 'xdc-interaction-detector';
+import { MemoryCheckpoint, FileCheckpoint, createCheckpointBackend } from '@xdc.org/interaction-detector';
 
 // ── Memory (development / testing) ───────────────────────────
 const memCp = new MemoryCheckpoint();
@@ -595,7 +597,7 @@ import {
 
   // Logger
   Logger, // new Logger('MyModule', 'info')
-} from 'xdc-interaction-detector';
+} from '@xdc.org/interaction-detector';
 ```
 
 ---
@@ -680,7 +682,7 @@ import {
 
 ```
 ┌──────────────────────────────────────────────────────────┐
-│              xdc-interaction-detector                    │
+│            @xdc.org/interaction-detector                     │
 │                                                          │
 │  ┌───────────────────────────────────────────────────┐   │
 │  │  ContractWatcher         (real-time monitoring)   │   │

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdc.org/interaction-detector",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Standalone TypeScript library for detecting all on-chain contract interactions — events, direct calls, internal calls, and transaction tracing — on XDC and EVM-compatible chains.",
   "author": "XinFinOrg",
   "license": "MIT",