@xdc.org/interaction-detector 1.0.0

package/dist/rpc/ws-manager.js

@@ -0,0 +1,161 @@
+/**
+ * WebSocket connection lifecycle manager.
+ * Handles connect, heartbeat, auto-reconnect, and event forwarding.
+ */
+import { EventEmitter } from 'events';
+import { WebSocketProvider } from 'ethers';
+import { Logger } from '../utils/logger.js';
+const WS_DEFAULTS = {
+    enabled: true,
+    reconnectDelayBaseMs: 5_000,
+    reconnectDelayMaxMs: 30_000,
+    maxReconnectAttempts: 20,
+    heartbeatIntervalMs: 60_000,
+    heartbeatTimeoutMs: 10_000,
+};
+export class WsManager extends EventEmitter {
+    logger;
+    wsUrl;
+    chainId;
+    config;
+    provider = null;
+    heartbeatTimer = null;
+    reconnectAttempts = 0;
+    reconnectScheduled = false;
+    _isConnected = false;
+    destroyed = false;
+    constructor(wsUrl, chainId, wsConfig, logLevel) {
+        super();
+        this.wsUrl = wsUrl;
+        this.chainId = chainId;
+        this.config = { ...WS_DEFAULTS, ...wsConfig };
+        this.logger = new Logger('WsManager', logLevel ?? 'info');
+    }
+    get isConnected() {
+        return this._isConnected;
+    }
+    async connect(addresses) {
+        if (this.destroyed)
+            return;
+        try {
+            this.logger.info(`Connecting to ${this.wsUrl}...`);
+            const WS = (await import('ws')).default;
+            const ws = new WS(this.wsUrl);
+            await new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => {
+                    ws.terminate();
+                    reject(new Error(`Connection timeout: ${this.wsUrl}`));
+                }, 10_000);
+                ws.once('open', () => { clearTimeout(timeout); resolve(); });
+                ws.once('error', (err) => { clearTimeout(timeout); reject(err); });
+            });
+            await this.destroyConnection();
+            this.provider = new WebSocketProvider(ws, this.chainId);
+            const filter = { address: addresses };
+            this.provider.on(filter, (log) => {
+                this.emit('log', log);
+            });
+            ws.on('close', () => {
+                if (!this._isConnected && this.reconnectScheduled)
+                    return;
+                this.logger.warn(`WS closed (${this.wsUrl})`);
+                this._isConnected = false;
+                this.stopHeartbeat();
+                this.destroyConnection().then(() => this.scheduleReconnect(addresses));
+            });
+            ws.on('error', (err) => {
+                if (!this._isConnected && this.reconnectScheduled)
+                    return;
+                this.logger.error(`WS error: ${err.message}`);
+                this._isConnected = false;
+                this.stopHeartbeat();
+                this.destroyConnection().then(() => this.scheduleReconnect(addresses));
+            });
+            this._isConnected = true;
+            this.reconnectAttempts = 0;
+            this.reconnectScheduled = false;
+            this.logger.info(`WS connected to ${this.wsUrl}`);
+            this.emit('connected', this.wsUrl);
+            this.startHeartbeat(addresses);
+        }
+        catch (error) {
+            this.logger.error(`WS connect failed: ${error.message}`);
+            this.emit('error', error);
+            this.scheduleReconnect(addresses);
+        }
+    }
+    async disconnect() {
+        this.destroyed = true;
+        this.stopHeartbeat();
+        await this.destroyConnection();
+        this._isConnected = false;
+    }
+    startHeartbeat(addresses) {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(async () => {
+            if (!this._isConnected || !this.provider) {
+                this.stopHeartbeat();
+                return;
+            }
+            try {
+                const blockNumber = await Promise.race([
+                    this.provider.getBlockNumber(),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error('heartbeat timeout')), this.config.heartbeatTimeoutMs)),
+                ]);
+                this.logger.debug(`Heartbeat OK — block ${blockNumber}`);
+            }
+            catch (err) {
+                if (!this._isConnected || this.reconnectScheduled)
+                    return;
+                this.logger.warn(`Heartbeat FAILED: ${err.message} — reconnecting`);
+                this._isConnected = false;
+                this.stopHeartbeat();
+                await this.destroyConnection();
+                this.scheduleReconnect(addresses);
+            }
+        }, this.config.heartbeatIntervalMs);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    scheduleReconnect(addresses) {
+        if (this.destroyed || this.reconnectScheduled)
+            return;
+        this.reconnectScheduled = true;
+        this.reconnectAttempts++;
+        if (this.reconnectAttempts > this.config.maxReconnectAttempts) {
+            this.logger.warn(`Exceeded ${this.config.maxReconnectAttempts} reconnect attempts. Retry in 5 min.`);
+            this.emit('disconnected', this.wsUrl, 'max_reconnect_exceeded');
+            setTimeout(() => {
+                if (!this.destroyed) {
+                    this.reconnectAttempts = 0;
+                    this.reconnectScheduled = false;
+                    this.connect(addresses).catch(() => { });
+                }
+            }, 5 * 60 * 1000);
+            return;
+        }
+        const delay = Math.min(this.config.reconnectDelayBaseMs * Math.pow(2, this.reconnectAttempts - 1), this.config.reconnectDelayMaxMs);
+        this.logger.info(`Reconnecting in ${delay / 1000}s (attempt ${this.reconnectAttempts})`);
+        this.emit('disconnected', this.wsUrl, 'reconnecting');
+        setTimeout(() => {
+            this.reconnectScheduled = false;
+            if (!this.destroyed)
+                this.connect(addresses).catch(() => { });
+        }, delay);
+    }
+    async destroyConnection() {
+        if (this.provider) {
+            try {
+                this.provider.removeAllListeners();
+                await this.provider.destroy();
+            }
+            catch { /* ignore */ }
+            this.provider = null;
+        }
+    }
+}
+//# sourceMappingURL=ws-manager.js.map

package/dist/rpc/ws-manager.js.map

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

package/dist/scanner/block-scanner.d.ts

@@ -0,0 +1,45 @@
+/**
+ * BlockScanner — Historical block range scanning.
+ *
+ * Scans a block range for all events and interactions involving a contract.
+ * Chunks requests into maxBlockRange-sized batches (default: 100 for XDC).
+ * Includes block timestamp resolution with LRU cache.
+ */
+import type { DecodedEvent, ContractInteraction, ScanOptions, ExplorerConfig, LogLevel } from '../types/index.js';
+export interface BlockScannerConfig {
+    /** Primary HTTP RPC URL */
+    rpcUrl: string;
+    /** Fallback RPC URLs */
+    fallbackRpcUrls?: string[];
+    /** Max blocks per request (default: 100) */
+    maxBlockRange?: number;
+    /** Parallel fetch concurrency (default: 3) */
+    concurrency?: number;
+    /** Explorer config (optional — enables txlist/txlistinternal) */
+    explorer?: ExplorerConfig;
+    /** Log level */
+    logLevel?: LogLevel;
+}
+export declare class BlockScanner {
+    private readonly logger;
+    private readonly logLevel;
+    private readonly rpc;
+    private readonly maxBlockRange;
+    private readonly concurrency;
+    private readonly explorerConfig?;
+    private timestampCache;
+    private readonly maxCacheSize;
+    constructor(config: BlockScannerConfig);
+    /**
+     * Scan a block range for all events from a contract.
+     * Returns decoded events sorted by block number and log index.
+     */
+    getEvents(options: ScanOptions): Promise<DecodedEvent[]>;
+    /**
+     * Scan a block range for all interactions (events + explorer txlist + txlistinternal).
+     * Returns unified ContractInteraction records.
+     */
+    getInteractions(options: ScanOptions): Promise<ContractInteraction[]>;
+    private resolveTimestamp;
+}
+//# sourceMappingURL=block-scanner.d.ts.map

package/dist/scanner/block-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-scanner.d.ts","sourceRoot":"","sources":["../../src/scanner/block-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,QAAQ,EACT,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,gBAAgB;IAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAiB;IAGjD,OAAO,CAAC,cAAc,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;gBAEzB,MAAM,EAAE,kBAAkB;IAatC;;;OAGG;IACG,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA8C9D;;;OAGG;IACG,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;YA4F7D,gBAAgB;CAkB/B"}

package/dist/scanner/block-scanner.js

@@ -0,0 +1,180 @@
+/**
+ * BlockScanner — Historical block range scanning.
+ *
+ * Scans a block range for all events and interactions involving a contract.
+ * Chunks requests into maxBlockRange-sized batches (default: 100 for XDC).
+ * Includes block timestamp resolution with LRU cache.
+ */
+import { Logger } from '../utils/logger.js';
+import { normalizeAddress } from '../utils/address.js';
+import { RpcClient } from '../rpc/rpc-client.js';
+import { LogPoller } from '../watcher/log-poller.js';
+import { EventDecoder } from '../decoder/event-decoder.js';
+import { AbiRegistry } from '../decoder/abi-registry.js';
+import { ExplorerClient } from '../explorer/explorer-client.js';
+export class BlockScanner {
+    logger;
+    logLevel;
+    rpc;
+    maxBlockRange;
+    concurrency;
+    explorerConfig;
+    // Block timestamp LRU cache
+    timestampCache = new Map();
+    maxCacheSize = 2000;
+    constructor(config) {
+        this.logLevel = config.logLevel ?? 'info';
+        this.logger = new Logger('BlockScanner', this.logLevel);
+        this.maxBlockRange = config.maxBlockRange ?? 100;
+        this.concurrency = config.concurrency ?? 3;
+        this.explorerConfig = config.explorer;
+        this.rpc = new RpcClient(config.rpcUrl, {
+            fallbackUrls: config.fallbackRpcUrls,
+            logLevel: this.logLevel,
+        });
+    }
+    /**
+     * Scan a block range for all events from a contract.
+     * Returns decoded events sorted by block number and log index.
+     */
+    async getEvents(options) {
+        const address = normalizeAddress(options.address);
+        const registry = new AbiRegistry(this.logLevel);
+        if (options.abi) {
+            registry.register(address, options.abi);
+        }
+        const decoder = new EventDecoder(registry, this.logLevel);
+        const poller = new LogPoller(this.rpc, [address], { maxBlockRange: this.maxBlockRange, concurrency: this.concurrency }, this.logLevel);
+        const totalBlocks = options.toBlock - options.fromBlock + 1;
+        this.logger.info(`Scanning ${totalBlocks} blocks (${options.fromBlock}–${options.toBlock}) for ${address}`);
+        const logs = await poller.fetchLogs(options.fromBlock, options.toBlock);
+        this.logger.info(`Found ${logs.length} raw logs`);
+        const events = [];
+        for (const log of logs) {
+            const decoded = decoder.decode(log);
+            if (!decoded)
+                continue;
+            if (options.eventFilter && decoded.name !== options.eventFilter)
+                continue;
+            decoded.timestamp = await this.resolveTimestamp(decoded.blockNumber);
+            events.push(decoded);
+            if (options.onProgress) {
+                const blocksProcessed = decoded.blockNumber - options.fromBlock;
+                options.onProgress(blocksProcessed, totalBlocks);
+            }
+        }
+        if (options.onProgress) {
+            options.onProgress(totalBlocks, totalBlocks);
+        }
+        this.logger.info(`Decoded ${events.length} events`);
+        return events;
+    }
+    /**
+     * Scan a block range for all interactions (events + explorer txlist + txlistinternal).
+     * Returns unified ContractInteraction records.
+     */
+    async getInteractions(options) {
+        const address = normalizeAddress(options.address);
+        const interactions = [];
+        // 1) Get events from RPC logs
+        const events = await this.getEvents(options);
+        const seenTxHashes = new Set();
+        for (const event of events) {
+            seenTxHashes.add(event.txHash);
+            interactions.push({
+                type: 'event',
+                txHash: event.txHash,
+                blockNumber: event.blockNumber,
+                timestamp: event.timestamp,
+                from: '',
+                to: event.contract,
+                value: '0',
+                event,
+                source: 'rpc_logs',
+            });
+        }
+        // 2) Get transactions from explorer (if configured)
+        if (this.explorerConfig) {
+            const explorer = new ExplorerClient(this.explorerConfig, this.logLevel);
+            try {
+                const txs = await explorer.getTransactions(address, {
+                    startBlock: options.fromBlock,
+                    endBlock: options.toBlock,
+                });
+                for (const tx of txs) {
+                    if (seenTxHashes.has(tx.hash))
+                        continue;
+                    seenTxHashes.add(tx.hash);
+                    interactions.push({
+                        type: 'direct_call',
+                        txHash: tx.hash,
+                        blockNumber: parseInt(tx.blockNumber),
+                        timestamp: parseInt(tx.timeStamp),
+                        from: tx.from,
+                        to: tx.to,
+                        value: tx.value,
+                        methodId: tx.methodId,
+                        methodName: tx.functionName,
+                        input: tx.input,
+                        gasUsed: tx.gasUsed,
+                        isError: tx.isError === '1',
+                        source: 'explorer_txlist',
+                    });
+                }
+                const internalTxs = await explorer.getInternalTransactions(address, {
+                    startBlock: options.fromBlock,
+                    endBlock: options.toBlock,
+                });
+                for (const tx of internalTxs) {
+                    const callType = tx.callType?.toLowerCase();
+                    let interactionType = 'internal_call';
+                    if (callType === 'delegatecall')
+                        interactionType = 'delegate_call';
+                    else if (callType === 'staticcall')
+                        interactionType = 'static_call';
+                    else if (callType === 'create')
+                        interactionType = 'create';
+                    interactions.push({
+                        type: interactionType,
+                        txHash: tx.hash,
+                        blockNumber: parseInt(tx.blockNumber),
+                        timestamp: parseInt(tx.timeStamp),
+                        from: tx.from,
+                        to: tx.to,
+                        value: tx.value,
+                        gasUsed: tx.gasUsed,
+                        isError: tx.isError === '1',
+                        source: 'explorer_internal',
+                    });
+                }
+            }
+            catch (err) {
+                this.logger.warn(`Explorer scan failed: ${err.message}`);
+            }
+            finally {
+                explorer.destroy();
+            }
+        }
+        interactions.sort((a, b) => a.blockNumber - b.blockNumber || a.timestamp - b.timestamp);
+        this.logger.info(`Total interactions: ${interactions.length}`);
+        return interactions;
+    }
+    async resolveTimestamp(blockNumber) {
+        const cached = this.timestampCache.get(blockNumber);
+        if (cached !== undefined)
+            return cached;
+        try {
+            const timestamp = await this.rpc.getBlockTimestamp(blockNumber);
+            this.timestampCache.set(blockNumber, timestamp);
+            if (this.timestampCache.size > this.maxCacheSize) {
+                const entries = Array.from(this.timestampCache.entries());
+                this.timestampCache = new Map(entries.slice(entries.length - (this.maxCacheSize / 2)));
+            }
+            return timestamp;
+        }
+        catch {
+            return 0;
+        }
+    }
+}
+//# sourceMappingURL=block-scanner.js.map

package/dist/scanner/block-scanner.js.map

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

package/dist/tracer/call-tree-parser.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Call Tree Parser — parses callTracer output into typed CallTreeNode.
+ *
+ * Recursively processes the nested call structure from debug_traceTransaction
+ * with callTracer, optionally decoding method signatures when ABI is available.
+ */
+import type { CallTreeNode } from '../types/index.js';
+import type { AbiRegistry } from '../decoder/abi-registry.js';
+/**
+ * Parse raw callTracer output into a typed CallTreeNode.
+ */
+export declare function parseCallTree(raw: any, depth?: number, registry?: AbiRegistry): CallTreeNode;
+/**
+ * Flatten a call tree into a linear array of all nodes.
+ */
+export declare function flattenCallTree(node: CallTreeNode): CallTreeNode[];
+/**
+ * Extract all unique contract addresses from a call tree.
+ */
+export declare function extractInvolvedContracts(node: CallTreeNode): string[];
+/**
+ * Find all calls targeting a specific contract address.
+ */
+export declare function findCallsTo(node: CallTreeNode, targetAddress: string): CallTreeNode[];
+//# sourceMappingURL=call-tree-parser.d.ts.map

package/dist/tracer/call-tree-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-tree-parser.d.ts","sourceRoot":"","sources":["../../src/tracer/call-tree-parser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAG9D;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,GAAE,MAAU,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,YAAY,CAsC/F;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,EAAE,CAMlE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,EAAE,CASrE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,GAAG,YAAY,EAAE,CAGrF"}

package/dist/tracer/call-tree-parser.js

@@ -0,0 +1,80 @@
+/**
+ * Call Tree Parser — parses callTracer output into typed CallTreeNode.
+ *
+ * Recursively processes the nested call structure from debug_traceTransaction
+ * with callTracer, optionally decoding method signatures when ABI is available.
+ */
+import { normalizeAddress } from '../utils/address.js';
+/**
+ * Parse raw callTracer output into a typed CallTreeNode.
+ */
+export function parseCallTree(raw, depth = 0, registry) {
+    const to = normalizeAddress(raw.to ?? '0x0000000000000000000000000000000000000000');
+    const from = normalizeAddress(raw.from ?? '');
+    let method;
+    if (raw.input && raw.input.length >= 10 && registry) {
+        const contract = registry.get(to);
+        if (contract) {
+            try {
+                const selector = raw.input.slice(0, 10);
+                const fragment = contract.iface.getFunction(selector);
+                if (fragment) {
+                    method = fragment.format('sighash');
+                }
+            }
+            catch { /* Unknown selector */ }
+        }
+    }
+    const node = {
+        type: raw.type ?? 'CALL',
+        from,
+        to,
+        value: raw.value ?? '0x0',
+        gas: raw.gas ?? '0x0',
+        gasUsed: raw.gasUsed ?? '0x0',
+        input: raw.input ?? '0x',
+        output: raw.output ?? '0x',
+        method,
+        error: raw.error,
+        calls: [],
+        depth,
+    };
+    if (raw.calls && Array.isArray(raw.calls)) {
+        node.calls = raw.calls.map((sub) => parseCallTree(sub, depth + 1, registry));
+    }
+    return node;
+}
+/**
+ * Flatten a call tree into a linear array of all nodes.
+ */
+export function flattenCallTree(node) {
+    const result = [node];
+    for (const child of node.calls) {
+        result.push(...flattenCallTree(child));
+    }
+    return result;
+}
+/**
+ * Extract all unique contract addresses from a call tree.
+ */
+export function extractInvolvedContracts(node) {
+    const addresses = new Set();
+    function walk(n) {
+        if (n.from)
+            addresses.add(normalizeAddress(n.from));
+        if (n.to)
+            addresses.add(normalizeAddress(n.to));
+        for (const child of n.calls)
+            walk(child);
+    }
+    walk(node);
+    return Array.from(addresses);
+}
+/**
+ * Find all calls targeting a specific contract address.
+ */
+export function findCallsTo(node, targetAddress) {
+    const target = normalizeAddress(targetAddress);
+    return flattenCallTree(node).filter((n) => normalizeAddress(n.to) === target);
+}
+//# sourceMappingURL=call-tree-parser.js.map

package/dist/tracer/call-tree-parser.js.map

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

package/dist/tracer/state-diff-parser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * State Diff Parser — parses prestateTracer output into typed StateDiff and BalanceChange.
+ */
+import type { StateDiff, BalanceChange } from '../types/index.js';
+/**
+ * Parse prestateTracer diffMode output into StateDiff entries.
+ */
+export declare function parseStateDiffs(raw: any): StateDiff[];
+/**
+ * Parse prestateTracer diffMode output into BalanceChange entries.
+ */
+export declare function parseBalanceChanges(raw: any): BalanceChange[];
+//# sourceMappingURL=state-diff-parser.d.ts.map

package/dist/tracer/state-diff-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-diff-parser.d.ts","sourceRoot":"","sources":["../../src/tracer/state-diff-parser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGlE;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,SAAS,EAAE,CAoCrD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,GAAG,GAAG,aAAa,EAAE,CA6B7D"}

package/dist/tracer/state-diff-parser.js

@@ -0,0 +1,70 @@
+/**
+ * State Diff Parser — parses prestateTracer output into typed StateDiff and BalanceChange.
+ */
+import { normalizeAddress } from '../utils/address.js';
+/**
+ * Parse prestateTracer diffMode output into StateDiff entries.
+ */
+export function parseStateDiffs(raw) {
+    if (!raw || !raw.pre || !raw.post)
+        return [];
+    const diffs = [];
+    const allAddresses = new Set([
+        ...Object.keys(raw.pre || {}),
+        ...Object.keys(raw.post || {}),
+    ]);
+    for (const address of allAddresses) {
+        const pre = raw.pre[address];
+        const post = raw.post[address];
+        const preStorage = pre?.storage ?? {};
+        const postStorage = post?.storage ?? {};
+        const allSlots = new Set([
+            ...Object.keys(preStorage),
+            ...Object.keys(postStorage),
+        ]);
+        for (const slot of allSlots) {
+            const before = preStorage[slot] ?? '0x0';
+            const after = postStorage[slot] ?? '0x0';
+            if (before !== after) {
+                diffs.push({
+                    contract: normalizeAddress(address),
+                    slot,
+                    before,
+                    after,
+                });
+            }
+        }
+    }
+    return diffs;
+}
+/**
+ * Parse prestateTracer diffMode output into BalanceChange entries.
+ */
+export function parseBalanceChanges(raw) {
+    if (!raw || !raw.pre || !raw.post)
+        return [];
+    const changes = [];
+    const allAddresses = new Set([
+        ...Object.keys(raw.pre || {}),
+        ...Object.keys(raw.post || {}),
+    ]);
+    for (const address of allAddresses) {
+        const pre = raw.pre[address];
+        const post = raw.post[address];
+        const beforeHex = pre?.balance ?? '0x0';
+        const afterHex = post?.balance ?? '0x0';
+        const before = BigInt(beforeHex);
+        const after = BigInt(afterHex);
+        if (before !== after) {
+            changes.push({
+                address: normalizeAddress(address),
+                token: 'native',
+                before,
+                after,
+                delta: after - before,
+            });
+        }
+    }
+    return changes;
+}
+//# sourceMappingURL=state-diff-parser.js.map

package/dist/tracer/state-diff-parser.js.map

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