@xdc.org/interaction-detector 1.0.0

package/README.md

@@ -0,0 +1,767 @@
+# XDC Interaction Detector
+
+Standalone TypeScript library for detecting **all on-chain contract interactions** on XDC and EVM-compatible chains.
+
+Combines: **events** + **direct calls** + **internal calls** + **transaction tracing** into a single unified detection engine.
+
+**Framework-agnostic. Zero runtime dependencies on any specific backend.** Just detection — you decide what to do with the results.
+
+## Table of Contents
+
+- [XDC Interaction Detector](#xdc-interaction-detector)
+  - [Table of Contents](#table-of-contents)
+  - [Features](#features)
+  - [Installation](#installation)
+  - [Quick Start](#quick-start)
+  - [Core Classes](#core-classes)
+    - [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)
+  - [Explorer API Client](#explorer-api-client)
+  - [Event Decoder \& ABI Registry](#event-decoder--abi-registry)
+  - [Checkpoint Persistence](#checkpoint-persistence)
+  - [Utility Functions](#utility-functions)
+  - [Configuration Reference](#configuration-reference)
+    - [InteractionDetectorConfig (ContractWatcher)](#interactiondetectorconfig-contractwatcher)
+    - [ContractConfig](#contractconfig)
+    - [ExplorerConfig](#explorerconfig)
+    - [PollingConfig](#pollingconfig)
+    - [WsConfig](#wsconfig)
+    - [CheckpointConfig](#checkpointconfig)
+  - [XDC-Specific Notes](#xdc-specific-notes)
+  - [Architecture](#architecture)
+  - [Examples](#examples)
+  - [Development](#development)
+  - [License](#license)
+
+---
+
+## Features
+
+- **Real-time event monitoring** — WebSocket push + HTTP polling with automatic deduplication
+- **Historical block scanning** — Query any block range with auto-chunked fetching
+- **Transaction tracing** — Full call trees, state diffs, and balance changes via `debug_traceTransaction`
+- **Explorer API integration** — Direct & internal transaction collection via XDCScan / Etherscan-compatible APIs
+- **XDC-first, EVM-compatible** — Handles XDC's non-standard ABI encoding, `xdc` address prefix, and 100-block range limit
+- **Pluggable checkpoints** — Memory, file, or custom backends for restart persistence
+- **Zero framework dependency** — Works in any Node.js environment: Express, Fastify, serverless functions, CLI scripts, background workers
+
+---
+
+## Installation
+
+```bash
+npm install xdc-interaction-detector
+```
+
+**Dependencies:** `ethers` v6, `axios`, `ws` — all installed automatically.
+
+---
+
+## Quick Start
+
+```typescript
+import { ContractWatcher } from 'xdc-interaction-detector';
+
+const watcher = new ContractWatcher({
+  // RPC endpoints
+  rpcUrl: 'https://rpc.xinfin.network',
+  wsUrl: 'wss://ws.xinfin.network', // optional — enables real-time push
+  chainId: 50, // XDC Mainnet
+
+  // Contracts to monitor
+  contracts: [
+    {
+      address: '0x0000000000000000000000000000000000000088',
+      abi: ['event Vote(address indexed _voter, address indexed _candidate, uint256 _cap)'],
+      name: 'XDCValidator',
+    },
+  ],
+
+  // Explorer API — enables direct & internal call detection
+  explorer: {
+    apiUrl: 'https://xdc.blocksscan.io/api',
+    apiKey: 'YOUR_API_KEY', // optional — higher rate limits
+    rateLimitPerSec: 5,
+  },
+
+  // Checkpoint — survive restarts
+  checkpoint: { backend: 'file', path: './checkpoints' },
+});
+
+// Decoded contract events (Transfer, Swap, Vote, etc.)
+watcher.on('event', event => {
+  console.log(`${event.name} from ${event.contractName} at block ${event.blockNumber}`);
+  console.log('  Args:', event.args);
+});
+
+// ALL interactions (events + direct + internal + delegate + static calls)
+watcher.on('interaction', interaction => {
+  console.log(`[${interaction.type}] tx ${interaction.txHash} (source: ${interaction.source})`);
+});
+
+await watcher.start();
+```
+
+---
+
+## Core Classes
+
+### 1. ContractWatcher — Real-Time Monitoring
+
+Watches one or more contract addresses for all interactions in real-time using three complementary detection paths:
+
+| Path         | Method                      | What it catches                     | Latency       |
+| ------------ | --------------------------- | ----------------------------------- | ------------- |
+| WebSocket    | `eth_subscribe("logs")`     | Contract events                     | ~2 seconds    |
+| HTTP Polling | `eth_getLogs`               | Contract events (reliable fallback) | 15–30 seconds |
+| Explorer API | `txlist` + `txlistinternal` | Direct calls + internal calls       | 30–60 seconds |
+
+**Creating a watcher:**
+
+```typescript
+import { ContractWatcher } from 'xdc-interaction-detector';
+
+const watcher = new ContractWatcher({
+  // ─── Required ───────────────────────────────────────────
+  rpcUrl: 'https://rpc.xinfin.network',
+  contracts: [
+    {
+      address: '0xContractAddress',       // 0x or xdc prefix both work
+      abi: [...],                          // optional — enables event decoding
+      name: 'MyDeFiPool',                 // optional — human label
+    },
+    // Watch multiple contracts simultaneously
+    { address: '0xAnotherContract', name: 'Governance' },
+  ],
+
+  // ─── Optional: WebSocket (real-time push) ───────────────
+  wsUrl: 'wss://ws.xinfin.network',
+  chainId: 50,                            // default: 50 (XDC Mainnet)
+
+  // ─── 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
+    rateLimitPerSec: 5,                    // default: 5 req/s
+    pollIntervalMs: 60_000,               // how often to check explorer (default: 60s)
+  },
+
+  // ─── Optional: Polling tuning ───────────────────────────
+  polling: {
+    intervalMs: 15_000,                    // default: 30s
+    maxBlockRange: 100,                    // XDC limit — don't change unless using another chain
+    concurrency: 3,                        // parallel chunk fetches
+  },
+
+  // ─── Optional: WebSocket tuning ─────────────────────────
+  ws: {
+    enabled: true,                         // default: true
+    reconnectDelayBaseMs: 5_000,
+    reconnectDelayMaxMs: 30_000,
+    maxReconnectAttempts: 20,
+    heartbeatIntervalMs: 60_000,
+    heartbeatTimeoutMs: 10_000,
+  },
+
+  // ─── Optional: Checkpoint persistence ───────────────────
+  checkpoint: {
+    backend: 'file',                       // 'memory' | 'file' | 'custom'
+    path: './checkpoints',
+  },
+
+  // ─── Optional: Fallback RPCs ────────────────────────────
+  fallbackRpcUrls: ['https://rpc1.xinfin.network'],
+
+  // ─── Optional: Log level ────────────────────────────────
+  logLevel: 'info',                        // 'debug' | 'info' | 'warn' | 'error' | 'silent'
+});
+```
+
+**Listening for events:**
+
+```typescript
+// ── Decoded contract events ──────────────────────────────────
+watcher.on('event', event => {
+  console.log(event.contract); // '0xcontractaddress'
+  console.log(event.contractName); // 'MyDeFiPool'
+  console.log(event.name); // 'Swap'
+  console.log(event.args); // { sender: '0x...', amount0In: 1000n, ... }
+  console.log(event.blockNumber); // 75123456
+  console.log(event.txHash); // '0xabc...'
+  console.log(event.logIndex); // 3
+  console.log(event.timestamp); // 1711792800 (Unix seconds)
+  console.log(event.signature); // 'Swap(address,uint256,uint256,address)'
+  console.log(event.raw); // { topics: [...], data: '0x...' }
+});
+
+// ── ALL interactions (unified type) ──────────────────────────
+watcher.on('interaction', interaction => {
+  console.log(interaction.type); // 'event' | 'direct_call' | 'internal_call' | 'delegate_call' | 'static_call'
+  console.log(interaction.source); // 'rpc_logs' | 'ws_logs' | 'explorer_txlist' | 'explorer_internal'
+  console.log(interaction.txHash);
+  console.log(interaction.from); // sender (when available)
+  console.log(interaction.to); // contract address
+  console.log(interaction.methodId); // '0xa9059cbb' (for direct/internal calls)
+  console.log(interaction.methodName); // 'transfer(address,uint256)' (if ABI found)
+  console.log(interaction.value); // native value in wei
+  console.log(interaction.isError); // true if call reverted
+});
+
+// ── Raw logs (for contracts without ABI) ─────────────────────
+watcher.on('log', log => {
+  console.log(log.topics[0]); // event signature hash
+  console.log(log.data); // raw encoded data
+});
+
+// ── Lifecycle events ─────────────────────────────────────────
+watcher.on('connected', info => {
+  console.log(`Connected via ${info.type}: ${info.url}`);
+});
+
+watcher.on('disconnected', info => {
+  console.log(`Disconnected: ${info.reason}`);
+});
+
+watcher.on('checkpoint', blockNumber => {
+  console.log(`Checkpoint saved at block ${blockNumber}`);
+});
+
+watcher.on('error', err => {
+  console.error(`Error: ${err.message}`);
+});
+```
+
+**Starting and stopping:**
+
+```typescript
+// Start monitoring
+await watcher.start();
+
+// ... later, graceful shutdown
+await watcher.stop();
+```
+
+**Deduplication:** Events detected by both WebSocket and polling are automatically deduplicated using `txHash + logIndex` composite keys. This prevents double-counting when both detection paths catch the same event.
+
+---
+
+### 2. BlockScanner — Historical Queries
+
+Scans a block range for all events and interactions involving a contract. Automatically handles XDC's 100-block `eth_getLogs` limit with chunked parallel fetching.
+
+**Scanning for events:**
+
+```typescript
+import { BlockScanner } from 'xdc-interaction-detector';
+
+const scanner = new BlockScanner({
+  rpcUrl: 'https://rpc.xinfin.network',
+  maxBlockRange: 100, // default: 100 (XDC limit)
+  concurrency: 3, // parallel chunk fetches
+  logLevel: 'info',
+
+  // Optional: explorer for direct + internal tx enrichment
+  explorer: {
+    apiUrl: 'https://xdc.blocksscan.io/api',
+    apiKey: 'YOUR_API_KEY',
+  },
+});
+
+// ── Scan for decoded events ──────────────────────────────────
+const events = await scanner.getEvents({
+  address: '0x0000000000000000000000000000000000000088',
+  abi: [
+    'event Vote(address indexed _voter, address indexed _candidate, uint256 _cap)',
+    'event Unvote(address indexed _voter, address indexed _candidate, uint256 _cap)',
+  ],
+  fromBlock: 75_000_000,
+  toBlock: 75_100_000,
+
+  // Optional: filter by specific event name
+  eventFilter: 'Vote',
+
+  // Optional: progress callback for large scans
+  onProgress: (processed, total) => {
+    console.log(`${Math.round((processed / total) * 100)}% complete`);
+  },
+});
+
+// events is DecodedEvent[]
+for (const event of events) {
+  console.log(`[block ${event.blockNumber}] ${event.name}`, event.args);
+}
+```
+
+**Scanning for all interactions (events + explorer txlist + txlistinternal):**
+
+```typescript
+const interactions = await scanner.getInteractions({
+  address: '0x0000000000000000000000000000000000000088',
+  abi: [...],
+  fromBlock: 75_000_000,
+  toBlock: 75_100_000,
+});
+
+// interactions is ContractInteraction[]
+for (const i of interactions) {
+  console.log(`[${i.type}] block ${i.blockNumber} tx ${i.txHash}`);
+  if (i.type === 'event') console.log('  Event:', i.event?.name, i.event?.args);
+  if (i.type === 'direct_call') console.log('  Method:', i.methodName);
+  if (i.type === 'internal_call') console.log('  From:', i.from);
+}
+```
+
+---
+
+### 3. TransactionTracer — Deep Transaction Analysis
+
+Traces a single transaction to extract the full execution story: call tree, state diffs, balance changes, and all events.
+
+> **Note:** Requires an RPC endpoint with the `debug` namespace enabled. For historical transactions, an archive node is required. For recent/current blocks, a regular full node works.
+
+**Full trace:**
+
+```typescript
+import { TransactionTracer } from 'xdc-interaction-detector';
+
+const tracer = new TransactionTracer({
+  rpcUrl: 'https://archive-rpc.xinfin.network', // must support debug_traceTransaction
+  timeoutMs: 120_000, // tracing can be slow on complex txs
+  logLevel: 'info',
+});
+
+// Register ABIs for method name decoding in call trees
+tracer.registerABI(
+  '0xContractAddress',
+  ['function swap(uint256,uint256,address,bytes)', 'function transfer(address,uint256)'],
+  'MyDEX',
+);
+
+const result = await tracer.trace('0xTransactionHash');
+```
+
+**Using the trace result:**
+
+```typescript
+// ── Call Tree ────────────────────────────────────────────────
+// Nested structure showing every CALL, STATICCALL, DELEGATECALL
+console.log(result.callTree.type); // 'CALL'
+console.log(result.callTree.from); // '0xSender'
+console.log(result.callTree.to); // '0xContract'
+console.log(result.callTree.method); // 'swap(uint256,uint256,address,bytes)' (if ABI registered)
+console.log(result.callTree.value); // '0x0' (native value)
+console.log(result.callTree.calls); // CallTreeNode[] — nested sub-calls
+// Example nested call:
+//   CALL 0xRouter → swap(...)
+//     CALL 0xPool → mint(...)
+//       STATICCALL 0xOracle → getPrice()
+//       CALL 0xTokenA → transfer(...)
+
+// ── State Diffs ──────────────────────────────────────────────
+// Storage slot changes (before/after for each modified slot)
+for (const diff of result.stateDiffs) {
+  console.log(`${diff.contract} slot ${diff.slot}`);
+  console.log(`  before: ${diff.before}`);
+  console.log(`  after:  ${diff.after}`);
+}
+
+// ── Balance Changes ──────────────────────────────────────────
+// Native token balance changes per address
+for (const change of result.balanceChanges) {
+  console.log(`${change.address}: ${change.delta} wei (${change.token})`);
+}
+
+// ── Events ───────────────────────────────────────────────────
+// All events emitted during execution (decoded if ABI registered)
+for (const event of result.events) {
+  console.log(`${event.name} from ${event.contract}`, event.args);
+}
+
+// ── Metadata ─────────────────────────────────────────────────
+console.log(result.gasUsed); // 234567
+console.log(result.involvedContracts); // ['0x...', '0x...', '0x...']
+console.log(result.blockNumber); // 75123456
+```
+
+**Partial traces (lighter weight):**
+
+```typescript
+// Just the call tree (no state diffs)
+const callTree = await tracer.traceCallTree('0xTxHash');
+
+// Just the state diffs + balance changes (no call tree)
+const { stateDiffs, balanceChanges } = await tracer.traceStateDiffs('0xTxHash');
+```
+
+**Call tree utilities:**
+
+```typescript
+import { flattenCallTree, findCallsTo, extractInvolvedContracts } from 'xdc-interaction-detector';
+
+// Flatten the nested tree into a linear array
+const allCalls = flattenCallTree(result.callTree);
+console.log(`Total calls in execution: ${allCalls.length}`);
+
+// Find all calls targeting a specific contract
+const tokenCalls = findCallsTo(result.callTree, '0xTokenAddress');
+
+// Get all unique addresses involved
+const addresses = extractInvolvedContracts(result.callTree);
+```
+
+---
+
+## 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';
+
+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
+  rateLimitPerSec: 5, // built-in token-bucket rate limiter
+});
+```
+
+**Available methods:**
+
+```typescript
+// ── Transaction lists ────────────────────────────────────────
+// Get external transactions to/from a contract
+const txs = await explorer.getTransactions('0xAddress', {
+  startBlock: 75_000_000,
+  endBlock: 75_100_000,
+  sort: 'asc', // or 'desc'
+});
+
+// Get internal transactions (CALL, DELEGATECALL from other contracts)
+const internalTxs = await explorer.getInternalTransactions('0xAddress', {
+  startBlock: 75_000_000,
+  endBlock: 75_100_000,
+});
+
+// Get internal transactions within a specific tx
+const txInternals = await explorer.getInternalTransactionsByTx('0xTxHash');
+
+// ── Events ───────────────────────────────────────────────────
+// Get event logs with optional topic filter
+const logs = await explorer.getLogs('0xAddress', {
+  fromBlock: 75_000_000,
+  toBlock: 75_100_000,
+  topic0: '0xddf252ad...', // optional — filter by event signature
+});
+
+// ── Contract ABI ─────────────────────────────────────────────
+// Auto-fetch verified contract ABI
+const abi = await explorer.getContractABI('0xAddress');
+if (abi) {
+  console.log(`Fetched ABI with ${abi.length} entries`);
+}
+
+// ── Token transfers ──────────────────────────────────────────
+const transfers = await explorer.getTokenTransfers('0xAddress', {
+  startBlock: 75_000_000,
+  endBlock: 75_100_000,
+});
+
+// ── Balance ──────────────────────────────────────────────────
+const balance = await explorer.getBalance('0xAddress');
+
+// ── Cleanup ──────────────────────────────────────────────────
+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    |
+
+---
+
+## Event Decoder & ABI Registry
+
+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';
+
+// ── Register ABIs ────────────────────────────────────────────
+const registry = new AbiRegistry();
+
+// Register manually
+registry.register(
+  '0xContractAddress',
+  [
+    'event Transfer(address indexed from, address indexed to, uint256 value)',
+    'event Approval(address indexed owner, address indexed spender, uint256 value)',
+  ],
+  'MyToken',
+);
+
+// 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' });
+const success = await registry.registerFromExplorer('0xVerifiedContract', explorer, 'VerifiedToken');
+console.log(success ? 'ABI fetched!' : 'Contract not verified');
+
+// ── Query the registry ───────────────────────────────────────
+registry.has('0xContractAddress'); // true
+registry.getName('0xContractAddress'); // 'MyToken'
+registry.getAddresses(); // ['0x...', '0x...']
+registry.getEventName('0xddf252ad...'); // 'Transfer' (from any registered contract)
+
+// ── Decode raw logs ──────────────────────────────────────────
+const decoder = new EventDecoder(registry);
+
+const decoded = decoder.decode(rawLog);
+if (decoded) {
+  console.log(decoded.name); // 'Transfer'
+  console.log(decoded.args.from); // '0x...'
+  console.log(decoded.args.to); // '0x...'
+  console.log(decoded.args.value); // 1000000000000000000n
+}
+```
+
+---
+
+## Checkpoint Persistence
+
+Checkpoints let the watcher resume from where it left off after a restart.
+
+```typescript
+import { MemoryCheckpoint, FileCheckpoint, createCheckpointBackend } from 'xdc-interaction-detector';
+
+// ── Memory (development / testing) ───────────────────────────
+const memCp = new MemoryCheckpoint();
+await memCp.save('watcher-key', 75_000_000);
+await memCp.load('watcher-key'); // 75000000
+
+// ── File (simple production) ─────────────────────────────────
+const fileCp = new FileCheckpoint('./checkpoints');
+await fileCp.save('watcher-key', 75_000_000);
+// Persists to ./checkpoints/checkpoints.json
+// Survives process restarts
+
+// ── Custom backend (bring your own) ──────────────────────────
+const customCp = {
+  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;
+  },
+};
+
+// ── Factory function ─────────────────────────────────────────
+const cp = createCheckpointBackend({ backend: 'file', path: './data' });
+const cp2 = createCheckpointBackend({ backend: 'custom', custom: customCp });
+```
+
+---
+
+## Utility Functions
+
+```typescript
+import {
+  // Address utilities
+  normalizeAddress, // '0xABC...' or 'xdcABC...' → '0xabc...'
+  toXdcAddress, // '0xabc...' → 'xdcabc...'
+  toEthAddress, // 'xdcabc...' → '0xabc...'
+  isAddress, // validate hex address (20 bytes)
+  addressEqual, // compare addresses (case-insensitive, prefix-aware)
+
+  // Formatting
+  formatXDC, // bigint wei → '1.23M XDC' / '456.78K XDC'
+  formatWei, // bigint wei → '1.23M' (generic, no unit)
+  parseHexOrDecimal, // '0x100' → 256, '256' → 256
+  toHex, // 256 → '0x100'
+  shortAddress, // '0x1234...abcd'
+  sleep, // await sleep(1000)
+
+  // Logger
+  Logger, // new Logger('MyModule', 'info')
+} from 'xdc-interaction-detector';
+```
+
+---
+
+## Configuration Reference
+
+### InteractionDetectorConfig (ContractWatcher)
+
+| Option            | Type               | Default    | Description                                  |
+| ----------------- | ------------------ | ---------- | -------------------------------------------- |
+| `rpcUrl`          | `string`           | _required_ | Primary HTTP RPC URL                         |
+| `wsUrl`           | `string`           | —          | WebSocket RPC URL (enables real-time events) |
+| `contracts`       | `ContractConfig[]` | _required_ | Contracts to monitor                         |
+| `explorer`        | `ExplorerConfig`   | —          | Block explorer API settings                  |
+| `polling`         | `PollingConfig`    | —          | HTTP polling tuning                          |
+| `ws`              | `WsConfig`         | —          | WebSocket tuning                             |
+| `checkpoint`      | `CheckpointConfig` | `memory`   | Checkpoint persistence                       |
+| `chainId`         | `number`           | `50`       | Chain ID                                     |
+| `fallbackRpcUrls` | `string[]`         | `[]`       | Fallback RPC endpoints                       |
+| `logLevel`        | `LogLevel`         | `'info'`   | Log verbosity                                |
+
+### ContractConfig
+
+| Option    | Type     | Default    | Description                                           |
+| --------- | -------- | ---------- | ----------------------------------------------------- |
+| `address` | `string` | _required_ | Contract address (`0x` or `xdc` prefix)               |
+| `abi`     | `any[]`  | —          | ABI for event decoding. Human-readable or JSON format |
+| `name`    | `string` | —          | Human-readable label (shown in decoded events)        |
+
+### ExplorerConfig
+
+| Option            | Type     | Default    | Description                             |
+| ----------------- | -------- | ---------- | --------------------------------------- |
+| `apiUrl`          | `string` | _required_ | Explorer API base URL                   |
+| `apiKey`          | `string` | —          | API key for higher rate limits          |
+| `chainId`         | `number` | —          | Chain ID (required for Etherscan v2)    |
+| `rateLimitPerSec` | `number` | `5`        | Max requests per second                 |
+| `pollIntervalMs`  | `number` | `60000`    | How often to poll txlist/txlistinternal |
+
+### PollingConfig
+
+| Option          | Type     | Default | Description                              |
+| --------------- | -------- | ------- | ---------------------------------------- |
+| `intervalMs`    | `number` | `30000` | How often to poll eth_getLogs            |
+| `maxBlockRange` | `number` | `100`   | Max blocks per request (XDC limit = 100) |
+| `concurrency`   | `number` | `3`     | Parallel chunk fetches                   |
+
+### WsConfig
+
+| Option                 | Type      | Default | Description                                   |
+| ---------------------- | --------- | ------- | --------------------------------------------- |
+| `enabled`              | `boolean` | `true`  | Enable WebSocket subscription                 |
+| `reconnectDelayBaseMs` | `number`  | `5000`  | Base reconnect delay                          |
+| `reconnectDelayMaxMs`  | `number`  | `30000` | Max reconnect delay (exponential backoff cap) |
+| `maxReconnectAttempts` | `number`  | `20`    | Max attempts before 5-min cooldown            |
+| `heartbeatIntervalMs`  | `number`  | `60000` | Heartbeat ping interval                       |
+| `heartbeatTimeoutMs`   | `number`  | `10000` | Heartbeat response timeout                    |
+
+### CheckpointConfig
+
+| Option    | Type                | Default           | Description                                  |
+| --------- | ------------------- | ----------------- | -------------------------------------------- |
+| `backend` | `string`            | `'memory'`        | `'memory'`, `'file'`, or `'custom'`          |
+| `path`    | `string`            | `'./checkpoints'` | Directory for `'file'` backend               |
+| `custom`  | `CheckpointBackend` | —                 | Custom implementation for `'custom'` backend |
+
+---
+
+## XDC-Specific Notes
+
+- **Non-standard ABI encoding:** Some XDC system contracts (including XDCValidator at `0x...0088`) encode all event parameters in the `data` field with only `topic[0]` (the event signature). Standard decoders like `ethers.js` fail on these. The library includes an automatic fallback decoder that handles this transparently.
+
+- **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`.
+
+- **Tracing:** `debug_traceTransaction` requires an archive node for historical transactions. For monitoring current blocks in real-time, a standard full node works fine.
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────┐
+│              xdc-interaction-detector                    │
+│                                                          │
+│  ┌───────────────────────────────────────────────────┐   │
+│  │  ContractWatcher         (real-time monitoring)   │   │
+│  │    ├── WsManager         (WebSocket subscription) │   │
+│  │    ├── LogPoller         (eth_getLogs fallback)   │   │
+│  │    ├── ExplorerClient    (txlist + txlistinternal)│   │
+│  │    ├── EventDecoder      (ABI + XDC fallback)     │   │
+│  │    └── Checkpoint        (pluggable persistence)  │   │
+│  └───────────────────────────────────────────────────┘   │
+│                                                          │
+│  ┌────────────────────────────────────────────────────┐  │
+│  │  BlockScanner            (historical queries)      │  │
+│  │    └── ExplorerClient    (API adapter)             │  │
+│  └────────────────────────────────────────────────────┘  │
+│                                                          │
+│  ┌────────────────────────────────────────────────────┐  │
+│  │  TransactionTracer       (debug_traceTransaction)  │  │
+│  │    ├── CallTreeParser    (callTracer output)       │  │
+│  │    └── StateDiffParser   (prestateTracer output)   │  │
+│  └────────────────────────────────────────────────────┘  │
+│                                                          │
+│  ┌────────────────────┐  ┌───────────────────────────┐   │
+│  │  RPC Client        │  │  Utilities                │   │
+│  │  (retry, timeout,  │  │  (address normalize,      │   │
+│  │   fallback, WS)    │  │   format, logger, cache)  │   │
+│  └────────────────────┘  └───────────────────────────┘   │
+└──────────────────────────────────────────────────────────┘
+```
+
+**Detection pipeline:**
+
+```
+Events (eth_subscribe + eth_getLogs)
+    ↓ collect tx hashes
+XDCScan (txlist + txlistinternal)
+    ↓ merge + deduplicate
+ContractInteraction records
+    ↓ optionally
+debug_traceTransaction (per tx hash)
+    ↓ parse call tree + state diffs
+Full execution story
+```
+
+---
+
+## Examples
+
+See the `examples/` directory for runnable scripts:
+
+| Example                        | What it demonstrates                       |
+| ------------------------------ | ------------------------------------------ |
+| `basic-watcher.ts`             | Real-time event monitoring with checkpoint |
+| `historical-scan.ts`           | Scanning a block range for events          |
+| `trace-transaction.ts`         | Deep-diving a single transaction           |
+| `full-interaction-detector.ts` | All 3 methods combined                     |
+
+Run any example with:
+
+```bash
+npx tsx examples/basic-watcher.ts
+npx tsx examples/trace-transaction.ts 0xYourTxHash
+```
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Compile TypeScript
+npm run build
+
+# Run unit tests (23 tests)
+npm test
+
+# Watch mode (auto-recompile on save)
+npm run dev
+```
+
+## License
+
+MIT