@xdc.org/interaction-detector 1.0.0

package/dist/checkpoint/checkpoint.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pluggable checkpoint persistence backends.
+ */
+import type { CheckpointBackend } from '../types/index.js';
+/**
+ * In-memory checkpoint — no persistence, for development/testing.
+ */
+export declare class MemoryCheckpoint implements CheckpointBackend {
+    private store;
+    save(key: string, blockNumber: number): Promise<void>;
+    load(key: string): Promise<number | null>;
+}
+/**
+ * File-based checkpoint — persists to a JSON file.
+ * Suitable for simple production deployments.
+ */
+export declare class FileCheckpoint implements CheckpointBackend {
+    private readonly filePath;
+    constructor(dirPath?: string);
+    save(key: string, blockNumber: number): Promise<void>;
+    load(key: string): Promise<number | null>;
+    private readFile;
+}
+/**
+ * Create a checkpoint backend from configuration.
+ */
+export declare function createCheckpointBackend(config?: {
+    backend: string;
+    path?: string;
+    custom?: CheckpointBackend;
+}): CheckpointBackend;
+//# sourceMappingURL=checkpoint.d.ts.map

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

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

package/dist/checkpoint/checkpoint.js

@@ -0,0 +1,68 @@
+/**
+ * Pluggable checkpoint persistence backends.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * In-memory checkpoint — no persistence, for development/testing.
+ */
+export class MemoryCheckpoint {
+    store = new Map();
+    async save(key, blockNumber) {
+        this.store.set(key, blockNumber);
+    }
+    async load(key) {
+        return this.store.get(key) ?? null;
+    }
+}
+/**
+ * File-based checkpoint — persists to a JSON file.
+ * Suitable for simple production deployments.
+ */
+export class FileCheckpoint {
+    filePath;
+    constructor(dirPath = './checkpoints') {
+        if (!fs.existsSync(dirPath)) {
+            fs.mkdirSync(dirPath, { recursive: true });
+        }
+        this.filePath = path.join(dirPath, 'checkpoints.json');
+    }
+    async save(key, blockNumber) {
+        const data = await this.readFile();
+        data[key] = blockNumber;
+        fs.writeFileSync(this.filePath, JSON.stringify(data, null, 2));
+    }
+    async load(key) {
+        const data = await this.readFile();
+        return data[key] ?? null;
+    }
+    async readFile() {
+        try {
+            if (fs.existsSync(this.filePath)) {
+                const content = fs.readFileSync(this.filePath, 'utf-8');
+                return JSON.parse(content);
+            }
+        }
+        catch { /* ignore corrupt file */ }
+        return {};
+    }
+}
+/**
+ * Create a checkpoint backend from configuration.
+ */
+export function createCheckpointBackend(config) {
+    if (!config)
+        return new MemoryCheckpoint();
+    switch (config.backend) {
+        case 'file':
+            return new FileCheckpoint(config.path);
+        case 'custom':
+            if (!config.custom)
+                throw new Error('Custom checkpoint backend not provided');
+            return config.custom;
+        case 'memory':
+        default:
+            return new MemoryCheckpoint();
+    }
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/checkpoint/checkpoint.js.map

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

package/dist/decoder/abi-registry.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ABI Registry — stores ABIs keyed by contract address.
+ * Supports topic hash → event name resolution and auto-fetch from explorer.
+ */
+import { Interface } from 'ethers';
+import type { ExplorerClient } from '../explorer/explorer-client.js';
+import type { LogLevel } from '../types/index.js';
+export interface RegisteredContract {
+    address: string;
+    iface: Interface;
+    name?: string;
+    /** topic0 hash → event name */
+    topicMap: Map<string, string>;
+}
+export declare class AbiRegistry {
+    private readonly logger;
+    private readonly contracts;
+    constructor(logLevel?: LogLevel);
+    /**
+     * Register a contract ABI for a given address.
+     */
+    register(address: string, abi: readonly any[] | any[], name?: string): void;
+    /**
+     * Auto-fetch ABI from block explorer and register it.
+     * Returns true if successful, false if ABI not found or not verified.
+     */
+    registerFromExplorer(address: string, explorer: ExplorerClient, name?: string): Promise<boolean>;
+    /**
+     * Get the registered contract info for an address.
+     */
+    get(address: string): RegisteredContract | undefined;
+    /**
+     * Check if an ABI is registered for this address.
+     */
+    has(address: string): boolean;
+    /**
+     * Get the event name for a topic0 hash from any registered contract.
+     */
+    getEventName(topic0: string): string | undefined;
+    /**
+     * Get all registered contract addresses.
+     */
+    getAddresses(): string[];
+    /**
+     * Get the human-readable name for a contract address.
+     */
+    getName(address: string): string | undefined;
+}
+//# sourceMappingURL=abi-registry.d.ts.map

package/dist/decoder/abi-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abi-registry.d.ts","sourceRoot":"","sources":["../../src/decoder/abi-registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAGnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8C;gBAE5D,QAAQ,CAAC,EAAE,QAAQ;IAI/B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAc3E;;;OAGG;IACG,oBAAoB,CACxB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,EACxB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC;IAuBnB;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIpD;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQhD;;OAEG;IACH,YAAY,IAAI,MAAM,EAAE;IAIxB;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAG7C"}

package/dist/decoder/abi-registry.js

@@ -0,0 +1,88 @@
+/**
+ * ABI Registry — stores ABIs keyed by contract address.
+ * Supports topic hash → event name resolution and auto-fetch from explorer.
+ */
+import { Interface } from 'ethers';
+import { normalizeAddress } from '../utils/address.js';
+import { Logger } from '../utils/logger.js';
+export class AbiRegistry {
+    logger;
+    contracts = new Map();
+    constructor(logLevel) {
+        this.logger = new Logger('AbiRegistry', logLevel ?? 'info');
+    }
+    /**
+     * Register a contract ABI for a given address.
+     */
+    register(address, abi, name) {
+        const normalizedAddr = normalizeAddress(address);
+        const iface = new Interface(abi);
+        // Build topic0 → event name map
+        const topicMap = new Map();
+        iface.forEachEvent((event) => {
+            topicMap.set(event.topicHash, event.name);
+        });
+        this.contracts.set(normalizedAddr, { address: normalizedAddr, iface, name, topicMap });
+        this.logger.debug(`Registered ABI for ${name ?? normalizedAddr} (${topicMap.size} events)`);
+    }
+    /**
+     * Auto-fetch ABI from block explorer and register it.
+     * Returns true if successful, false if ABI not found or not verified.
+     */
+    async registerFromExplorer(address, explorer, name) {
+        const normalizedAddr = normalizeAddress(address);
+        // Skip if already registered
+        if (this.contracts.has(normalizedAddr)) {
+            this.logger.debug(`ABI already registered for ${name ?? normalizedAddr}`);
+            return true;
+        }
+        try {
+            const abi = await explorer.getContractABI(address);
+            if (abi && Array.isArray(abi) && abi.length > 0) {
+                this.register(address, abi, name);
+                this.logger.info(`Auto-fetched ABI for ${name ?? normalizedAddr} (${abi.length} entries)`);
+                return true;
+            }
+        }
+        catch (err) {
+            this.logger.warn(`Failed to auto-fetch ABI for ${normalizedAddr}: ${err.message}`);
+        }
+        return false;
+    }
+    /**
+     * Get the registered contract info for an address.
+     */
+    get(address) {
+        return this.contracts.get(normalizeAddress(address));
+    }
+    /**
+     * Check if an ABI is registered for this address.
+     */
+    has(address) {
+        return this.contracts.has(normalizeAddress(address));
+    }
+    /**
+     * Get the event name for a topic0 hash from any registered contract.
+     */
+    getEventName(topic0) {
+        for (const contract of this.contracts.values()) {
+            const name = contract.topicMap.get(topic0);
+            if (name)
+                return name;
+        }
+        return undefined;
+    }
+    /**
+     * Get all registered contract addresses.
+     */
+    getAddresses() {
+        return Array.from(this.contracts.keys());
+    }
+    /**
+     * Get the human-readable name for a contract address.
+     */
+    getName(address) {
+        return this.contracts.get(normalizeAddress(address))?.name;
+    }
+}
+//# sourceMappingURL=abi-registry.js.map

package/dist/decoder/abi-registry.js.map

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

package/dist/decoder/event-decoder.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Generic event decoder — ABI-aware with XDC non-standard fallback.
+ *
+ * Primary: ethers Interface.parseLog() for standard ABI encoding.
+ * Fallback: manual byte-offset extraction for XDC non-standard encoding
+ * (all indexed params packed into data field with only topic[0]).
+ */
+import type { DecodedEvent, RawLog, LogLevel } from '../types/index.js';
+import { AbiRegistry } from './abi-registry.js';
+export declare class EventDecoder {
+    private readonly logger;
+    private readonly registry;
+    constructor(registry: AbiRegistry, logLevel?: LogLevel);
+    /**
+     * Decode a raw log into a DecodedEvent.
+     * Returns null if no ABI is registered or decoding fails entirely.
+     * Always provides raw log data regardless of decode success.
+     */
+    decode(log: RawLog): DecodedEvent | null;
+    /**
+     * XDC non-standard fallback decoder.
+     * All parameters (including indexed ones) are ABI-encoded in the data field,
+     * with only topic[0] (event signature) in topics.
+     */
+    private decodeFromDataFallback;
+    /**
+     * Extract 32-byte words from hex data for manual inspection.
+     */
+    private extractWordsFromData;
+}
+//# sourceMappingURL=event-decoder.d.ts.map

package/dist/decoder/event-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-decoder.d.ts","sourceRoot":"","sources":["../../src/decoder/event-decoder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIhD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;gBAE3B,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,QAAQ;IAKtD;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IA2DxC;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAyD9B;;OAEG;IACH,OAAO,CAAC,oBAAoB;CAQ7B"}

package/dist/decoder/event-decoder.js

@@ -0,0 +1,142 @@
+/**
+ * Generic event decoder — ABI-aware with XDC non-standard fallback.
+ *
+ * Primary: ethers Interface.parseLog() for standard ABI encoding.
+ * Fallback: manual byte-offset extraction for XDC non-standard encoding
+ * (all indexed params packed into data field with only topic[0]).
+ */
+import { AbiCoder } from 'ethers';
+import { Logger } from '../utils/logger.js';
+import { normalizeAddress } from '../utils/address.js';
+import { parseHexOrDecimal } from '../utils/format.js';
+const abiCoder = AbiCoder.defaultAbiCoder();
+export class EventDecoder {
+    logger;
+    registry;
+    constructor(registry, logLevel) {
+        this.registry = registry;
+        this.logger = new Logger('EventDecoder', logLevel ?? 'info');
+    }
+    /**
+     * Decode a raw log into a DecodedEvent.
+     * Returns null if no ABI is registered or decoding fails entirely.
+     * Always provides raw log data regardless of decode success.
+     */
+    decode(log) {
+        if (!log || !log.topics || log.topics.length === 0)
+            return null;
+        const address = normalizeAddress(log.address);
+        const contract = this.registry.get(address);
+        const blockNumber = parseHexOrDecimal(log.blockNumber);
+        const logIndex = parseHexOrDecimal(log.logIndex);
+        // Base event (always populated)
+        const baseEvent = {
+            contract: address,
+            contractName: contract?.name,
+            blockNumber,
+            txHash: log.transactionHash,
+            logIndex,
+            timestamp: 0, // filled by caller
+            raw: log,
+        };
+        if (!contract) {
+            // No ABI registered — return event with topic0 as name
+            const eventName = this.registry.getEventName(log.topics[0]);
+            return {
+                ...baseEvent,
+                name: eventName ?? 'UnknownEvent',
+                signature: log.topics[0],
+                args: {},
+            };
+        }
+        // Try standard ethers decoding first
+        try {
+            const parsed = contract.iface.parseLog({
+                topics: log.topics,
+                data: log.data,
+            });
+            if (parsed) {
+                const args = {};
+                parsed.fragment.inputs.forEach((input, i) => {
+                    args[input.name] = parsed.args[i];
+                });
+                return {
+                    ...baseEvent,
+                    name: parsed.name,
+                    signature: parsed.signature,
+                    args,
+                };
+            }
+        }
+        catch {
+            // ethers failed (BUFFER_OVERRUN) — try XDC fallback
+        }
+        // Fallback: XDC non-standard encoding
+        // All params packed into data field with only topic[0]
+        return this.decodeFromDataFallback(baseEvent, log, contract);
+    }
+    /**
+     * XDC non-standard fallback decoder.
+     * All parameters (including indexed ones) are ABI-encoded in the data field,
+     * with only topic[0] (event signature) in topics.
+     */
+    decodeFromDataFallback(baseEvent, log, contract) {
+        const topic0 = log.topics[0];
+        const eventName = contract.topicMap.get(topic0);
+        if (!eventName)
+            return null;
+        const data = log.data;
+        if (!data || data.length < 66) {
+            return {
+                ...baseEvent,
+                name: eventName,
+                signature: topic0,
+                args: {},
+            };
+        }
+        // Try to decode all params from data field
+        try {
+            const eventFragment = contract.iface.getEvent(eventName);
+            if (!eventFragment) {
+                return { ...baseEvent, name: eventName, signature: topic0, args: {} };
+            }
+            // Decode using all inputs as non-indexed (since they're all in data)
+            const types = eventFragment.inputs.map((i) => i.type);
+            const decoded = abiCoder.decode(types, data);
+            const args = {};
+            eventFragment.inputs.forEach((input, i) => {
+                args[input.name] = decoded[i];
+            });
+            this.logger.debug(`Decoded ${eventName} via XDC fallback (${types.length} params)`);
+            return {
+                ...baseEvent,
+                name: eventName,
+                signature: eventFragment.format('sighash'),
+                args,
+            };
+        }
+        catch (err) {
+            this.logger.debug(`Fallback decode failed for ${eventName}: ${err.message}`);
+            // Last resort — return with raw data, manual extraction
+            const args = this.extractWordsFromData(data);
+            return {
+                ...baseEvent,
+                name: eventName,
+                signature: topic0,
+                args: { _rawWords: args },
+            };
+        }
+    }
+    /**
+     * Extract 32-byte words from hex data for manual inspection.
+     */
+    extractWordsFromData(data) {
+        const words = [];
+        const hex = data.startsWith('0x') ? data.slice(2) : data;
+        for (let i = 0; i < hex.length; i += 64) {
+            words.push('0x' + hex.slice(i, i + 64));
+        }
+        return words;
+    }
+}
+//# sourceMappingURL=event-decoder.js.map

package/dist/decoder/event-decoder.js.map

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

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

@@ -0,0 +1,65 @@
+/**
+ * Etherscan-compatible block explorer API client.
+ *
+ * Works with: XDCScan, Etherscan v2, BSCScan, PolygonScan, and any
+ * Etherscan-compatible API by changing the base URL.
+ */
+import type { ExplorerConfig, ExplorerTransaction, LogLevel } from '../types/index.js';
+export declare class ExplorerClient {
+    private readonly logger;
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly chainId?;
+    private readonly rateLimiter;
+    constructor(config: ExplorerConfig, logLevel?: LogLevel);
+    /**
+     * Get external transactions for an address (txlist).
+     */
+    getTransactions(address: string, options?: {
+        startBlock?: number;
+        endBlock?: number;
+        sort?: 'asc' | 'desc';
+    }): Promise<ExplorerTransaction[]>;
+    /**
+     * Get internal transactions for an address (txlistinternal).
+     */
+    getInternalTransactions(address: string, options?: {
+        startBlock?: number;
+        endBlock?: number;
+        sort?: 'asc' | 'desc';
+    }): Promise<ExplorerTransaction[]>;
+    /**
+     * Get internal transactions within a specific transaction (txlistinternal by txhash).
+     */
+    getInternalTransactionsByTx(txHash: string): Promise<ExplorerTransaction[]>;
+    /**
+     * Get event logs for an address (getLogs).
+     */
+    getLogs(address: string, options?: {
+        fromBlock?: number;
+        toBlock?: number;
+        topic0?: string;
+    }): Promise<any[]>;
+    /**
+     * Get verified contract ABI from explorer.
+     */
+    getContractABI(address: string): Promise<any[] | null>;
+    /**
+     * Get ERC-20 / XRC-20 token transfers for an address.
+     */
+    getTokenTransfers(address: string, options?: {
+        startBlock?: number;
+        endBlock?: number;
+        sort?: 'asc' | 'desc';
+    }): Promise<any[]>;
+    /**
+     * Get native balance for an address.
+     */
+    getBalance(address: string): Promise<string>;
+    /**
+     * Destroy the client and clean up rate limiter.
+     */
+    destroy(): void;
+    private request;
+}
+//# sourceMappingURL=explorer-client.d.ts.map

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

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