@xdc.org/interaction-detector 1.0.0

package/dist/explorer/explorer-client.js

@@ -0,0 +1,164 @@
+/**
+ * Etherscan-compatible block explorer API client.
+ *
+ * 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 {
+    logger;
+    baseUrl;
+    apiKey;
+    chainId;
+    rateLimiter;
+    constructor(config, logLevel) {
+        this.baseUrl = config.apiUrl.replace(/\/+$/, '');
+        this.apiKey = config.apiKey;
+        this.chainId = config.chainId;
+        this.rateLimiter = new RateLimiter(config.rateLimitPerSec ?? 5);
+        this.logger = new Logger('ExplorerClient', logLevel ?? 'info');
+    }
+    /**
+     * Get external transactions for an address (txlist).
+     */
+    async getTransactions(address, options) {
+        const params = {
+            module: 'account',
+            action: 'txlist',
+            address,
+            startblock: String(options?.startBlock ?? 0),
+            endblock: String(options?.endBlock ?? 99999999),
+            sort: options?.sort ?? 'asc',
+        };
+        const results = await this.request(params);
+        return (results ?? []).map((tx) => ({ ...tx, txType: 'external' }));
+    }
+    /**
+     * Get internal transactions for an address (txlistinternal).
+     */
+    async getInternalTransactions(address, options) {
+        const params = {
+            module: 'account',
+            action: 'txlistinternal',
+            address,
+            startblock: String(options?.startBlock ?? 0),
+            endblock: String(options?.endBlock ?? 99999999),
+            sort: options?.sort ?? 'asc',
+        };
+        const results = await this.request(params);
+        return (results ?? []).map((tx) => ({ ...tx, txType: 'internal' }));
+    }
+    /**
+     * Get internal transactions within a specific transaction (txlistinternal by txhash).
+     */
+    async getInternalTransactionsByTx(txHash) {
+        const params = {
+            module: 'account',
+            action: 'txlistinternal',
+            txhash: txHash,
+        };
+        const results = await this.request(params);
+        return (results ?? []).map((tx) => ({ ...tx, txType: 'internal' }));
+    }
+    /**
+     * Get event logs for an address (getLogs).
+     */
+    async getLogs(address, options) {
+        const params = {
+            module: 'logs',
+            action: 'getLogs',
+            address,
+            fromBlock: String(options?.fromBlock ?? 0),
+            toBlock: String(options?.toBlock ?? 99999999),
+        };
+        if (options?.topic0) {
+            params.topic0 = options.topic0;
+        }
+        return (await this.request(params)) ?? [];
+    }
+    /**
+     * Get verified contract ABI from explorer.
+     */
+    async getContractABI(address) {
+        const params = {
+            module: 'contract',
+            action: 'getabi',
+            address,
+        };
+        try {
+            const result = await this.request(params);
+            if (result && typeof result === 'string') {
+                return JSON.parse(result);
+            }
+        }
+        catch (err) {
+            this.logger.debug(`Failed to fetch ABI for ${address}: ${err.message}`);
+        }
+        return null;
+    }
+    /**
+     * Get ERC-20 / XRC-20 token transfers for an address.
+     */
+    async getTokenTransfers(address, options) {
+        const params = {
+            module: 'account',
+            action: 'tokentx',
+            address,
+            startblock: String(options?.startBlock ?? 0),
+            endblock: String(options?.endBlock ?? 99999999),
+            sort: options?.sort ?? 'asc',
+        };
+        return (await this.request(params)) ?? [];
+    }
+    /**
+     * Get native balance for an address.
+     */
+    async getBalance(address) {
+        const params = {
+            module: 'account',
+            action: 'balance',
+            address,
+        };
+        return (await this.request(params)) ?? '0';
+    }
+    /**
+     * Destroy the client and clean up rate limiter.
+     */
+    destroy() {
+        this.rateLimiter.destroy();
+    }
+    // ─── Internal ─────────────────────────────────────────────────────────
+    async request(params) {
+        await this.rateLimiter.acquire();
+        if (this.apiKey) {
+            params.apikey = this.apiKey;
+        }
+        // Add chainId for Etherscan v2 unified endpoint
+        if (this.chainId && this.baseUrl.includes('etherscan.io')) {
+            params.chainid = String(this.chainId);
+        }
+        try {
+            const response = await axios.get(this.baseUrl, {
+                params,
+                timeout: 15000,
+            });
+            const data = response.data;
+            if (data.status === '0' && data.message === 'No transactions found') {
+                return [];
+            }
+            if (data.status === '0' && data.message !== 'No transactions found') {
+                const msg = data.result || data.message || 'Unknown error';
+                this.logger.warn(`Explorer API error: ${msg}`);
+                return null;
+            }
+            return data.result;
+        }
+        catch (err) {
+            this.logger.error(`Explorer request failed: ${err.message}`);
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=explorer-client.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,31 @@
+/**
+ * Token-bucket rate limiter for API calls.
+ * Ensures we don't exceed N requests per second.
+ */
+export declare class RateLimiter {
+    private readonly maxTokens;
+    private readonly refillRateMs;
+    private tokens;
+    private lastRefill;
+    private queue;
+    private drainTimer;
+    /**
+     * @param maxPerSecond Maximum requests per second (default: 5)
+     */
+    constructor(maxPerSecond?: number);
+    /**
+     * Acquire a token. Resolves when a request slot is available.
+     */
+    acquire(): Promise<void>;
+    /**
+     * Get the number of queued requests waiting.
+     */
+    get pending(): number;
+    /**
+     * Destroy the rate limiter and clear timers.
+     */
+    destroy(): void;
+    private refill;
+    private startDrain;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

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

@@ -0,0 +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"}

package/dist/explorer/rate-limiter.js

@@ -0,0 +1,79 @@
+/**
+ * Token-bucket rate limiter for API calls.
+ * Ensures we don't exceed N requests per second.
+ */
+export class RateLimiter {
+    maxTokens;
+    refillRateMs;
+    tokens;
+    lastRefill;
+    queue = [];
+    drainTimer = null;
+    /**
+     * @param maxPerSecond Maximum requests per second (default: 5)
+     */
+    constructor(maxPerSecond = 5) {
+        this.maxTokens = maxPerSecond;
+        this.refillRateMs = 1000 / maxPerSecond;
+        this.tokens = maxPerSecond;
+        this.lastRefill = Date.now();
+    }
+    /**
+     * Acquire a token. Resolves when a request slot is available.
+     */
+    async acquire() {
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return;
+        }
+        // Queue the request — it will be resolved when tokens are available
+        return new Promise((resolve) => {
+            this.queue.push({ resolve });
+            this.startDrain();
+        });
+    }
+    /**
+     * Get the number of queued requests waiting.
+     */
+    get pending() {
+        return this.queue.length;
+    }
+    /**
+     * Destroy the rate limiter and clear timers.
+     */
+    destroy() {
+        if (this.drainTimer) {
+            clearInterval(this.drainTimer);
+            this.drainTimer = null;
+        }
+        for (const item of this.queue) {
+            item.resolve();
+        }
+        this.queue = [];
+    }
+    refill() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        const newTokens = elapsed / this.refillRateMs;
+        this.tokens = Math.min(this.maxTokens, this.tokens + newTokens);
+        this.lastRefill = now;
+    }
+    startDrain() {
+        if (this.drainTimer)
+            return;
+        this.drainTimer = setInterval(() => {
+            this.refill();
+            while (this.queue.length > 0 && this.tokens >= 1) {
+                this.tokens -= 1;
+                const item = this.queue.shift();
+                item.resolve();
+            }
+            if (this.queue.length === 0) {
+                clearInterval(this.drainTimer);
+                this.drainTimer = null;
+            }
+        }, this.refillRateMs);
+    }
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/explorer/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/explorer/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,OAAO,WAAW;IACL,SAAS,CAAS;IAClB,YAAY,CAAS;IAC9B,MAAM,CAAS;IACf,UAAU,CAAS;IACnB,KAAK,GAAmC,EAAE,CAAC;IAC3C,UAAU,GAA0B,IAAI,CAAC;IAEjD;;OAEG;IACH,YAAY,eAAuB,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,YAAY,CAAC;QAC9B,IAAI,CAAC,YAAY,GAAG,IAAI,GAAG,YAAY,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,MAAM,EAAE,CAAC;QAEd,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;YACjB,OAAO;QACT,CAAC;QAED,oEAAoE;QACpE,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YACnC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;YAC7B,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACzB,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;IAClB,CAAC;IAEO,MAAM;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC;QACtC,MAAM,SAAS,GAAG,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC;QAC9C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;QAChE,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;IACxB,CAAC;IAEO,UAAU;QAChB,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO;QAE5B,IAAI,CAAC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE;YACjC,IAAI,CAAC,MAAM,EAAE,CAAC;YAEd,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;gBACjD,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;gBACjB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAG,CAAC;gBACjC,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,CAAC;YAED,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5B,aAAa,CAAC,IAAI,CAAC,UAAW,CAAC,CAAC;gBAChC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACzB,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACxB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * XDC Interaction Detector — Public API
+ */
+export { ContractWatcher } from './watcher/contract-watcher.js';
+export { BlockScanner } from './scanner/block-scanner.js';
+export type { BlockScannerConfig } from './scanner/block-scanner.js';
+export { TransactionTracer } from './tracer/transaction-tracer.js';
+export type { TransactionTracerConfig } from './tracer/transaction-tracer.js';
+export { ExplorerClient } from './explorer/explorer-client.js';
+export { RateLimiter } from './explorer/rate-limiter.js';
+export { RpcClient } from './rpc/rpc-client.js';
+export type { RpcClientOptions } from './rpc/rpc-client.js';
+export { WsManager } from './rpc/ws-manager.js';
+export { EventDecoder } from './decoder/event-decoder.js';
+export { AbiRegistry } from './decoder/abi-registry.js';
+export type { RegisteredContract } from './decoder/abi-registry.js';
+export { MemoryCheckpoint, FileCheckpoint, createCheckpointBackend } from './checkpoint/checkpoint.js';
+export { parseCallTree, flattenCallTree, extractInvolvedContracts, findCallsTo } from './tracer/call-tree-parser.js';
+export { parseStateDiffs, parseBalanceChanges } from './tracer/state-diff-parser.js';
+export { normalizeAddress, toXdcAddress, toEthAddress, isAddress, addressEqual } from './utils/address.js';
+export { formatXDC, formatWei, parseHexOrDecimal, toHex, shortAddress, sleep } from './utils/format.js';
+export { Logger } from './utils/logger.js';
+export type { InteractionDetectorConfig, ContractConfig, ExplorerConfig, PollingConfig, WsConfig, CheckpointConfig, CheckpointBackend, RawLog, DecodedEvent, InteractionType, ContractInteraction, TracerResult, CallTreeNode, StateDiff, BalanceChange, ExplorerTransaction, ScanOptions, LogLevel, } from './types/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,YAAY,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAG9E,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAGzD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGhD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,YAAY,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAGpE,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAGvG,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AACrH,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAGrF,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC3G,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,iBAAiB,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AACxG,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,YAAY,EACV,yBAAyB,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,QAAQ,EAClF,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,EAC1E,mBAAmB,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EACzE,mBAAmB,EAAE,WAAW,EAAE,QAAQ,GAC3C,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * XDC Interaction Detector — Public API
+ */
+// Core classes
+export { ContractWatcher } from './watcher/contract-watcher.js';
+export { BlockScanner } from './scanner/block-scanner.js';
+export { TransactionTracer } from './tracer/transaction-tracer.js';
+// Explorer
+export { ExplorerClient } from './explorer/explorer-client.js';
+export { RateLimiter } from './explorer/rate-limiter.js';
+// RPC
+export { RpcClient } from './rpc/rpc-client.js';
+export { WsManager } from './rpc/ws-manager.js';
+// Decoder
+export { EventDecoder } from './decoder/event-decoder.js';
+export { AbiRegistry } from './decoder/abi-registry.js';
+// Checkpoint
+export { MemoryCheckpoint, FileCheckpoint, createCheckpointBackend } from './checkpoint/checkpoint.js';
+// Tracer utilities
+export { parseCallTree, flattenCallTree, extractInvolvedContracts, findCallsTo } from './tracer/call-tree-parser.js';
+export { parseStateDiffs, parseBalanceChanges } from './tracer/state-diff-parser.js';
+// Utilities
+export { normalizeAddress, toXdcAddress, toEthAddress, isAddress, addressEqual } from './utils/address.js';
+export { formatXDC, formatWei, parseHexOrDecimal, toHex, shortAddress, sleep } from './utils/format.js';
+export { Logger } from './utils/logger.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAe;AACf,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGnE,WAAW;AACX,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEzD,MAAM;AACN,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,UAAU;AACV,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD,aAAa;AACb,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAEvG,mBAAmB;AACnB,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AACrH,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAErF,YAAY;AACZ,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC3G,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,iBAAiB,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AACxG,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/rpc/rpc-client.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Standalone JSON-RPC client with retry and fallback.
+ */
+import type { RawLog, LogLevel } from '../types/index.js';
+export interface RpcClientOptions {
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Base delay between retries in ms (default: 1000) */
+    retryDelayMs?: number;
+    /** Request timeout in ms (default: 30000) */
+    timeoutMs?: number;
+    /** Fallback RPC URLs */
+    fallbackUrls?: string[];
+    /** Log level */
+    logLevel?: LogLevel;
+}
+export declare class RpcClient {
+    private readonly logger;
+    private readonly primaryUrl;
+    private readonly fallbackUrls;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private readonly timeoutMs;
+    private requestId;
+    constructor(primaryUrl: string, options?: RpcClientOptions);
+    /**
+     * Call a JSON-RPC method with retry and fallback logic.
+     */
+    call<T = any>(method: string, params?: any[]): Promise<T>;
+    /**
+     * Get the current block number.
+     */
+    getBlockNumber(): Promise<number>;
+    /**
+     * Get logs matching a filter.
+     */
+    getLogs(filter: {
+        address?: string | string[];
+        topics?: (string | string[] | null)[];
+        fromBlock: string | number;
+        toBlock: string | number;
+    }): Promise<RawLog[]>;
+    /**
+     * Get a block by number (with or without full tx objects).
+     */
+    getBlockByNumber(blockNumber: number, includeTransactions?: boolean): Promise<any>;
+    /**
+     * Get block timestamp (cached internally by callers for efficiency).
+     */
+    getBlockTimestamp(blockNumber: number): Promise<number>;
+    /**
+     * Get transaction receipt.
+     */
+    getTransactionReceipt(txHash: string): Promise<any>;
+    /**
+     * Get transaction by hash.
+     */
+    getTransaction(txHash: string): Promise<any>;
+    /**
+     * Call debug_traceTransaction (requires debug namespace enabled).
+     */
+    traceTransaction(txHash: string, tracerConfig: any): Promise<any>;
+    /**
+     * Get storage at a specific slot.
+     */
+    getStorageAt(address: string, slot: string, blockTag?: string): Promise<string>;
+    private callWithRetry;
+    private execute;
+}
+//# sourceMappingURL=rpc-client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-client.d.ts","sourceRoot":"","sources":["../../src/rpc/rpc-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB;IAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAgBD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAW;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,SAAS,CAAK;gBAEV,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAS1D;;OAEG;IACG,IAAI,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,GAAG,EAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAkBnE;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAKvC;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE;QACpB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;QAC5B,MAAM,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QACtC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;QAC3B,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;KAC1B,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAUrB;;OAEG;IACG,gBAAgB,CACpB,WAAW,EAAE,MAAM,EACnB,mBAAmB,UAAQ,GAC1B,OAAO,CAAC,GAAG,CAAC;IAIf;;OAEG;IACG,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAM7D;;OAEG;IACG,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAIzD;;OAEG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAIlD;;OAEG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAIvE;;OAEG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAW,GAAG,OAAO,CAAC,MAAM,CAAC;YAMzE,aAAa;YAmBb,OAAO;CAqBtB"}

package/dist/rpc/rpc-client.js

@@ -0,0 +1,136 @@
+/**
+ * Standalone JSON-RPC client with retry and fallback.
+ */
+import axios from 'axios';
+import { Logger } from '../utils/logger.js';
+import { sleep } from '../utils/format.js';
+import { toHex } from '../utils/format.js';
+export class RpcClient {
+    logger;
+    primaryUrl;
+    fallbackUrls;
+    maxRetries;
+    retryDelayMs;
+    timeoutMs;
+    requestId = 1;
+    constructor(primaryUrl, options) {
+        this.primaryUrl = primaryUrl;
+        this.fallbackUrls = options?.fallbackUrls ?? [];
+        this.maxRetries = options?.maxRetries ?? 3;
+        this.retryDelayMs = options?.retryDelayMs ?? 1000;
+        this.timeoutMs = options?.timeoutMs ?? 30000;
+        this.logger = new Logger('RpcClient', options?.logLevel ?? 'warn');
+    }
+    /**
+     * Call a JSON-RPC method with retry and fallback logic.
+     */
+    async call(method, params = []) {
+        const urls = [this.primaryUrl, ...this.fallbackUrls];
+        let lastError = null;
+        for (const url of urls) {
+            try {
+                return await this.callWithRetry(url, method, params);
+            }
+            catch (error) {
+                lastError = error;
+                this.logger.warn(`RPC ${method} failed on ${url}: ${error.message}`);
+            }
+        }
+        throw lastError || new Error(`RPC ${method} failed on all endpoints`);
+    }
+    // ─── Convenience Methods ──────────────────────────────────────────────
+    /**
+     * Get the current block number.
+     */
+    async getBlockNumber() {
+        const hex = await this.call('eth_blockNumber');
+        return parseInt(hex, 16);
+    }
+    /**
+     * Get logs matching a filter.
+     */
+    async getLogs(filter) {
+        const params = {
+            address: filter.address,
+            topics: filter.topics,
+            fromBlock: typeof filter.fromBlock === 'number' ? toHex(filter.fromBlock) : filter.fromBlock,
+            toBlock: typeof filter.toBlock === 'number' ? toHex(filter.toBlock) : filter.toBlock,
+        };
+        return this.call('eth_getLogs', [params]);
+    }
+    /**
+     * Get a block by number (with or without full tx objects).
+     */
+    async getBlockByNumber(blockNumber, includeTransactions = false) {
+        return this.call('eth_getBlockByNumber', [toHex(blockNumber), includeTransactions]);
+    }
+    /**
+     * Get block timestamp (cached internally by callers for efficiency).
+     */
+    async getBlockTimestamp(blockNumber) {
+        const block = await this.getBlockByNumber(blockNumber, false);
+        if (!block || !block.timestamp)
+            return 0;
+        return parseInt(block.timestamp, 16);
+    }
+    /**
+     * Get transaction receipt.
+     */
+    async getTransactionReceipt(txHash) {
+        return this.call('eth_getTransactionReceipt', [txHash]);
+    }
+    /**
+     * Get transaction by hash.
+     */
+    async getTransaction(txHash) {
+        return this.call('eth_getTransactionByHash', [txHash]);
+    }
+    /**
+     * Call debug_traceTransaction (requires debug namespace enabled).
+     */
+    async traceTransaction(txHash, tracerConfig) {
+        return this.call('debug_traceTransaction', [txHash, tracerConfig]);
+    }
+    /**
+     * Get storage at a specific slot.
+     */
+    async getStorageAt(address, slot, blockTag = 'latest') {
+        return this.call('eth_getStorageAt', [address, slot, blockTag]);
+    }
+    // ─── Internal ─────────────────────────────────────────────────────────
+    async callWithRetry(url, method, params) {
+        let lastError = null;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            try {
+                return await this.execute(url, method, params);
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < this.maxRetries - 1) {
+                    const delay = this.retryDelayMs * Math.pow(2, attempt);
+                    this.logger.debug(`Retry ${attempt + 1}/${this.maxRetries} for ${method} after ${delay}ms`);
+                    await sleep(delay);
+                }
+            }
+        }
+        throw lastError || new Error(`RPC ${method} failed after ${this.maxRetries} attempts`);
+    }
+    async execute(url, method, params) {
+        const request = {
+            jsonrpc: '2.0',
+            method,
+            params,
+            id: this.requestId++,
+        };
+        const config = {
+            timeout: this.timeoutMs,
+            headers: { 'Content-Type': 'application/json' },
+        };
+        const response = await axios.post(url, request, config);
+        if (response.data.error) {
+            throw new Error(`RPC error: ${response.data.error.message} (code: ${response.data.error.code})`);
+        }
+        return response.data.result;
+    }
+}
+//# sourceMappingURL=rpc-client.js.map

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

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

package/dist/rpc/ws-manager.d.ts

@@ -0,0 +1,27 @@
+/**
+ * WebSocket connection lifecycle manager.
+ * Handles connect, heartbeat, auto-reconnect, and event forwarding.
+ */
+import { EventEmitter } from 'events';
+import type { WsConfig, LogLevel } from '../types/index.js';
+export declare class WsManager extends EventEmitter {
+    private readonly logger;
+    private readonly wsUrl;
+    private readonly chainId;
+    private readonly config;
+    private provider;
+    private heartbeatTimer;
+    private reconnectAttempts;
+    private reconnectScheduled;
+    private _isConnected;
+    private destroyed;
+    constructor(wsUrl: string, chainId: number, wsConfig?: WsConfig, logLevel?: LogLevel);
+    get isConnected(): boolean;
+    connect(addresses: string[]): Promise<void>;
+    disconnect(): Promise<void>;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private destroyConnection;
+}
+//# sourceMappingURL=ws-manager.d.ts.map

package/dist/rpc/ws-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-manager.d.ts","sourceRoot":"","sources":["../../src/rpc/ws-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAItC,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAW5D,qBAAa,SAAU,SAAQ,YAAY;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAE5C,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,SAAS,CAAS;gBAEd,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,QAAQ;IAQpF,IAAI,WAAW,IAAI,OAAO,CAEzB;IAEK,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAyD3C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOjC,OAAO,CAAC,cAAc;IA0BtB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,iBAAiB;YA+BX,iBAAiB;CAShC"}