@xdc.org/interaction-detector 1.0.0

package/dist/tracer/transaction-tracer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * TransactionTracer — Deep transaction analysis via debug_traceTransaction.
+ *
+ * Wraps the XDC/Geth debug namespace to extract:
+ *   - Full call tree (callTracer)
+ *   - State diffs (prestateTracer with diffMode)
+ *   - Balance changes
+ *   - All involved contracts
+ *   - Events emitted during execution
+ *
+ * NOTE: Requires an archive node for historical transactions.
+ * For real-time monitoring (current blocks), a regular full node works.
+ */
+import type { TracerResult, CallTreeNode, StateDiff, BalanceChange, LogLevel } from '../types/index.js';
+export interface TransactionTracerConfig {
+    /** RPC URL (must support debug namespace) */
+    rpcUrl: string;
+    /** Fallback RPC URLs */
+    fallbackRpcUrls?: string[];
+    /** Request timeout in ms (default: 60000 — tracing can be slow) */
+    timeoutMs?: number;
+    /** Log level */
+    logLevel?: LogLevel;
+}
+export declare class TransactionTracer {
+    private readonly logger;
+    private readonly logLevel;
+    private readonly rpc;
+    private readonly registry;
+    private readonly decoder;
+    constructor(config: TransactionTracerConfig);
+    /**
+     * Register an ABI for method name decoding in call trees.
+     */
+    registerABI(address: string, abi: any[], name?: string): void;
+    /**
+     * Full trace: call tree + state diffs + balance changes + events.
+     */
+    trace(txHash: string): Promise<TracerResult>;
+    /**
+     * Trace only the call tree (callTracer).
+     */
+    traceCallTree(txHash: string): Promise<CallTreeNode>;
+    /**
+     * Trace only state diffs (prestateTracer with diffMode).
+     */
+    traceStateDiffs(txHash: string): Promise<{
+        stateDiffs: StateDiff[];
+        balanceChanges: BalanceChange[];
+    }>;
+}
+//# sourceMappingURL=transaction-tracer.d.ts.map

package/dist/tracer/transaction-tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-tracer.d.ts","sourceRoot":"","sources":["../../src/tracer/transaction-tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,aAAa,EAEb,QAAQ,EACT,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,uBAAuB;IACtC,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB;IAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,qBAAa,iBAAiB;IAC5B,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,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;gBAE3B,MAAM,EAAE,uBAAuB;IAc3C;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAI7D;;OAEG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA2ClD;;OAEG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAM1D;;OAEG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,SAAS,EAAE,CAAC;QAAC,cAAc,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC;CAQ7G"}

package/dist/tracer/transaction-tracer.js

@@ -0,0 +1,107 @@
+/**
+ * TransactionTracer — Deep transaction analysis via debug_traceTransaction.
+ *
+ * Wraps the XDC/Geth debug namespace to extract:
+ *   - Full call tree (callTracer)
+ *   - State diffs (prestateTracer with diffMode)
+ *   - Balance changes
+ *   - All involved contracts
+ *   - Events emitted during execution
+ *
+ * NOTE: Requires an archive node for historical transactions.
+ * For real-time monitoring (current blocks), a regular full node works.
+ */
+import { Logger } from '../utils/logger.js';
+import { RpcClient } from '../rpc/rpc-client.js';
+import { EventDecoder } from '../decoder/event-decoder.js';
+import { AbiRegistry } from '../decoder/abi-registry.js';
+import { parseCallTree, extractInvolvedContracts } from './call-tree-parser.js';
+import { parseStateDiffs, parseBalanceChanges } from './state-diff-parser.js';
+export class TransactionTracer {
+    logger;
+    logLevel;
+    rpc;
+    registry;
+    decoder;
+    constructor(config) {
+        this.logLevel = config.logLevel ?? 'info';
+        this.logger = new Logger('TransactionTracer', this.logLevel);
+        this.rpc = new RpcClient(config.rpcUrl, {
+            fallbackUrls: config.fallbackRpcUrls,
+            timeoutMs: config.timeoutMs ?? 60000,
+            logLevel: this.logLevel,
+        });
+        this.registry = new AbiRegistry(this.logLevel);
+        this.decoder = new EventDecoder(this.registry, this.logLevel);
+    }
+    /**
+     * Register an ABI for method name decoding in call trees.
+     */
+    registerABI(address, abi, name) {
+        this.registry.register(address, abi, name);
+    }
+    /**
+     * Full trace: call tree + state diffs + balance changes + events.
+     */
+    async trace(txHash) {
+        this.logger.info(`Tracing transaction: ${txHash}`);
+        const [callTreeRaw, stateDiffRaw, receipt] = await Promise.all([
+            this.rpc.traceTransaction(txHash, { tracer: 'callTracer' }),
+            this.rpc.traceTransaction(txHash, {
+                tracer: 'prestateTracer',
+                tracerConfig: { diffMode: true },
+            }).catch((err) => {
+                this.logger.warn(`prestateTracer failed: ${err.message}`);
+                return null;
+            }),
+            this.rpc.getTransactionReceipt(txHash),
+        ]);
+        const callTree = parseCallTree(callTreeRaw, 0, this.registry);
+        const stateDiffs = stateDiffRaw ? parseStateDiffs(stateDiffRaw) : [];
+        const balanceChanges = stateDiffRaw ? parseBalanceChanges(stateDiffRaw) : [];
+        const involvedContracts = extractInvolvedContracts(callTree);
+        const events = [];
+        if (receipt?.logs) {
+            for (const log of receipt.logs) {
+                const decoded = this.decoder.decode(log);
+                if (decoded)
+                    events.push(decoded);
+            }
+        }
+        const blockNumber = receipt?.blockNumber
+            ? (typeof receipt.blockNumber === 'string' ? parseInt(receipt.blockNumber, 16) : receipt.blockNumber)
+            : 0;
+        const gasUsed = receipt?.gasUsed
+            ? (typeof receipt.gasUsed === 'string' ? parseInt(receipt.gasUsed, 16) : receipt.gasUsed)
+            : 0;
+        this.logger.info(`Trace complete: ${countNodes(callTree)} calls, ${stateDiffs.length} state diffs, ` +
+            `${balanceChanges.length} balance changes, ${events.length} events`);
+        return { txHash, blockNumber, callTree, stateDiffs, balanceChanges, events, gasUsed, involvedContracts };
+    }
+    /**
+     * Trace only the call tree (callTracer).
+     */
+    async traceCallTree(txHash) {
+        this.logger.info(`Tracing call tree: ${txHash}`);
+        const raw = await this.rpc.traceTransaction(txHash, { tracer: 'callTracer' });
+        return parseCallTree(raw, 0, this.registry);
+    }
+    /**
+     * Trace only state diffs (prestateTracer with diffMode).
+     */
+    async traceStateDiffs(txHash) {
+        this.logger.info(`Tracing state diffs: ${txHash}`);
+        const raw = await this.rpc.traceTransaction(txHash, {
+            tracer: 'prestateTracer',
+            tracerConfig: { diffMode: true },
+        });
+        return { stateDiffs: parseStateDiffs(raw), balanceChanges: parseBalanceChanges(raw) };
+    }
+}
+function countNodes(node) {
+    let count = 1;
+    for (const child of node.calls)
+        count += countNodes(child);
+    return count;
+}
+//# sourceMappingURL=transaction-tracer.js.map

package/dist/tracer/transaction-tracer.js.map

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

package/dist/types/index.d.ts

@@ -0,0 +1,262 @@
+/**
+ * XDC Interaction Detector — Core Type Definitions
+ *
+ * Standalone types with zero framework dependencies.
+ * Covers: configuration, events, logs, tracing, explorer, interactions.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/** Main configuration for ContractWatcher */
+export interface InteractionDetectorConfig {
+    /** Primary HTTP RPC URL */
+    rpcUrl: string;
+    /** WebSocket RPC URL (optional — enables real-time event push) */
+    wsUrl?: string;
+    /** Contracts to monitor */
+    contracts: ContractConfig[];
+    /** Block explorer API settings (optional — enables direct/internal tx collection) */
+    explorer?: ExplorerConfig;
+    /** Polling configuration */
+    polling?: PollingConfig;
+    /** WebSocket configuration */
+    ws?: WsConfig;
+    /** Checkpoint persistence configuration */
+    checkpoint?: CheckpointConfig;
+    /** Log level (default: 'info') */
+    logLevel?: LogLevel;
+    /** Chain ID (default: 50 for XDC Mainnet) */
+    chainId?: number;
+    /** Fallback RPC URLs for retry */
+    fallbackRpcUrls?: string[];
+}
+/** Per-contract configuration */
+export interface ContractConfig {
+    /** Contract address (0x or xdc prefix supported) */
+    address: string;
+    /** Contract ABI (optional — enables event decoding) */
+    abi?: readonly any[] | any[];
+    /** Human-readable name (optional — appears in decoded events) */
+    name?: string;
+}
+/** Block explorer API configuration (Etherscan-compatible) */
+export interface ExplorerConfig {
+    /** Base API URL (e.g. 'https://xdc.blocksscan.io/api' or 'https://api.etherscan.io/v2/api') */
+    apiUrl: string;
+    /** API key (optional — higher rate limits) */
+    apiKey?: string;
+    /** Chain ID for Etherscan v2 unified endpoint (required for Etherscan v2) */
+    chainId?: number;
+    /** Max requests per second (default: 5) */
+    rateLimitPerSec?: number;
+    /** Polling interval in ms for txlist/txlistinternal (default: 60000) */
+    pollIntervalMs?: number;
+}
+/** Polling configuration for eth_getLogs fallback */
+export interface PollingConfig {
+    /** Polling interval in ms (default: 30000) */
+    intervalMs?: number;
+    /** Max blocks per eth_getLogs request (default: 100 for XDC) */
+    maxBlockRange?: number;
+    /** Number of parallel chunk fetches (default: 3) */
+    concurrency?: number;
+}
+/** WebSocket configuration */
+export interface WsConfig {
+    /** Enable WebSocket subscription (default: true) */
+    enabled?: boolean;
+    /** Base delay between reconnect attempts in ms (default: 5000) */
+    reconnectDelayBaseMs?: number;
+    /** Maximum reconnect delay in ms (default: 30000) */
+    reconnectDelayMaxMs?: number;
+    /** Maximum reconnect attempts before long backoff (default: 20) */
+    maxReconnectAttempts?: number;
+    /** Heartbeat interval in ms (default: 60000) */
+    heartbeatIntervalMs?: number;
+    /** Heartbeat timeout in ms (default: 10000) */
+    heartbeatTimeoutMs?: number;
+}
+/** Checkpoint persistence configuration */
+export interface CheckpointConfig {
+    /** Backend type: 'memory' (dev), 'file' (simple prod), or 'custom' */
+    backend: 'memory' | 'file' | 'custom';
+    /** File path for 'file' backend (default: './checkpoints') */
+    path?: string;
+    /** Custom backend implementation */
+    custom?: CheckpointBackend;
+}
+export interface CheckpointBackend {
+    save(key: string, blockNumber: number): Promise<void>;
+    load(key: string): Promise<number | null>;
+}
+export interface RawLog {
+    address: string;
+    topics: string[];
+    data: string;
+    blockNumber: string | number;
+    transactionHash: string;
+    transactionIndex: string | number;
+    logIndex: string | number;
+    blockHash: string;
+    removed?: boolean;
+}
+export interface DecodedEvent {
+    /** Normalized contract address (lowercase 0x) */
+    contract: string;
+    /** Human-readable contract name (from config) */
+    contractName?: string;
+    /** Event name (e.g. 'Transfer', 'Swap', 'Vote') */
+    name: string;
+    /** Event signature (e.g. 'transfer(address,uint256)') */
+    signature: string;
+    /** Decoded event arguments (named) */
+    args: Record<string, any>;
+    /** Block number */
+    blockNumber: number;
+    /** Transaction hash */
+    txHash: string;
+    /** Log index within the transaction */
+    logIndex: number;
+    /** Block timestamp (Unix seconds) */
+    timestamp: number;
+    /** Raw log data */
+    raw: RawLog;
+}
+/** How a contract was involved in a transaction */
+export type InteractionType = 'event' | 'direct_call' | 'internal_call' | 'delegate_call' | 'static_call' | 'create' | 'self_destruct';
+/** Unified interaction record combining all detection methods */
+export interface ContractInteraction {
+    /** How the contract was involved */
+    type: InteractionType;
+    /** Transaction hash */
+    txHash: string;
+    /** Block number */
+    blockNumber: number;
+    /** Block timestamp (Unix seconds) */
+    timestamp: number;
+    /** Transaction sender (from) */
+    from: string;
+    /** Transaction recipient / contract address */
+    to: string;
+    /** Native value transferred (wei) */
+    value: string;
+    /** Decoded event (if type == 'event') */
+    event?: DecodedEvent;
+    /** Function selector (first 4 bytes of input) */
+    methodId?: string;
+    /** Decoded method name (if ABI available) */
+    methodName?: string;
+    /** Input calldata */
+    input?: string;
+    /** Gas used */
+    gasUsed?: string;
+    /** Whether the call failed/reverted */
+    isError?: boolean;
+    /** Source of the interaction detection */
+    source: 'rpc_logs' | 'ws_logs' | 'explorer_txlist' | 'explorer_internal' | 'tracer';
+}
+/** Full trace result for a single transaction */
+export interface TracerResult {
+    /** Transaction hash */
+    txHash: string;
+    /** Block number */
+    blockNumber: number;
+    /** Full call tree (nested) */
+    callTree: CallTreeNode;
+    /** Storage slot state diffs */
+    stateDiffs: StateDiff[];
+    /** Native / token balance changes per address */
+    balanceChanges: BalanceChange[];
+    /** All events emitted during execution (decoded if ABI available) */
+    events: DecodedEvent[];
+    /** Total gas used */
+    gasUsed: number;
+    /** All contract addresses involved in execution */
+    involvedContracts: string[];
+}
+/** Single node in the call tree (recursive) */
+export interface CallTreeNode {
+    /** Call type: CALL, STATICCALL, DELEGATECALL, CREATE, CREATE2 */
+    type: string;
+    /** Caller address */
+    from: string;
+    /** Callee address */
+    to: string;
+    /** Native value transferred (hex) */
+    value: string;
+    /** Gas provided */
+    gas: string;
+    /** Gas used */
+    gasUsed: string;
+    /** Input calldata (hex) */
+    input: string;
+    /** Output / return data (hex) */
+    output: string;
+    /** Decoded method signature (if ABI available) */
+    method?: string;
+    /** Error message (if call reverted) */
+    error?: string;
+    /** Nested sub-calls */
+    calls: CallTreeNode[];
+    /** Depth in the call tree (0 = top-level) */
+    depth: number;
+}
+/** Storage slot state diff from prestateTracer */
+export interface StateDiff {
+    /** Contract address whose storage changed */
+    contract: string;
+    /** Storage slot key */
+    slot: string;
+    /** Value before execution */
+    before: string;
+    /** Value after execution */
+    after: string;
+}
+/** Balance change for an address */
+export interface BalanceChange {
+    /** Address that had a balance change */
+    address: string;
+    /** Token address ('native' for XDC/ETH) */
+    token: string;
+    /** Balance before */
+    before: bigint;
+    /** Balance after */
+    after: bigint;
+    /** Change (after - before) */
+    delta: bigint;
+}
+/** Transaction from explorer API (txlist endpoint) */
+export interface ExplorerTransaction {
+    hash: string;
+    blockNumber: string;
+    timeStamp: string;
+    from: string;
+    to: string;
+    value: string;
+    gas: string;
+    gasUsed: string;
+    gasPrice: string;
+    input: string;
+    methodId: string;
+    functionName: string;
+    isError: string;
+    contractAddress: string;
+    /** 'external' from txlist, 'internal' from txlistinternal */
+    txType: 'external' | 'internal';
+    /** Call type for internal txs (call, delegatecall, staticcall, create) */
+    callType?: string;
+}
+/** Block scanner query options */
+export interface ScanOptions {
+    /** Contract address to scan */
+    address: string;
+    /** Contract ABI (optional) */
+    abi?: readonly any[] | any[];
+    /** Start block (inclusive) */
+    fromBlock: number;
+    /** End block (inclusive) */
+    toBlock: number;
+    /** Filter by specific event name (optional) */
+    eventFilter?: string;
+    /** Progress callback (blocks processed / total) */
+    onProgress?: (processed: number, total: number) => void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

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

package/dist/types/index.js

@@ -0,0 +1,8 @@
+/**
+ * XDC Interaction Detector — Core Type Definitions
+ *
+ * Standalone types with zero framework dependencies.
+ * Covers: configuration, events, logs, tracing, explorer, interactions.
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/utils/address.d.ts

@@ -0,0 +1,29 @@
+/**
+ * XDC address utilities.
+ *
+ * Handles the XDC-specific `xdc` prefix alongside standard `0x`.
+ * All internal operations use lowercase `0x` format.
+ */
+/**
+ * Normalize an address to lowercase `0x` format.
+ * Converts `xdc` prefix to `0x`, strips whitespace, lowercases.
+ */
+export declare function normalizeAddress(address: string): string;
+/**
+ * Convert a `0x` address to `xdc` prefixed format.
+ */
+export declare function toXdcAddress(address: string): string;
+/**
+ * Convert an `xdc` address to standard `0x` format.
+ * Alias for normalizeAddress since it already handles this.
+ */
+export declare function toEthAddress(address: string): string;
+/**
+ * Validate that a string is a valid hex address (20 bytes).
+ */
+export declare function isAddress(address: string): boolean;
+/**
+ * Check if two addresses are the same (case-insensitive, prefix-aware).
+ */
+export declare function addressEqual(a: string, b: string): boolean;
+//# sourceMappingURL=address.d.ts.map

package/dist/utils/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../../src/utils/address.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOxD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAIlD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAE1D"}

package/dist/utils/address.js

@@ -0,0 +1,49 @@
+/**
+ * XDC address utilities.
+ *
+ * Handles the XDC-specific `xdc` prefix alongside standard `0x`.
+ * All internal operations use lowercase `0x` format.
+ */
+/**
+ * Normalize an address to lowercase `0x` format.
+ * Converts `xdc` prefix to `0x`, strips whitespace, lowercases.
+ */
+export function normalizeAddress(address) {
+    if (!address)
+        return address;
+    let normalized = address.trim().toLowerCase();
+    if (normalized.startsWith('xdc')) {
+        normalized = '0x' + normalized.slice(3);
+    }
+    return normalized;
+}
+/**
+ * Convert a `0x` address to `xdc` prefixed format.
+ */
+export function toXdcAddress(address) {
+    const normalized = normalizeAddress(address);
+    return 'xdc' + normalized.slice(2);
+}
+/**
+ * Convert an `xdc` address to standard `0x` format.
+ * Alias for normalizeAddress since it already handles this.
+ */
+export function toEthAddress(address) {
+    return normalizeAddress(address);
+}
+/**
+ * Validate that a string is a valid hex address (20 bytes).
+ */
+export function isAddress(address) {
+    if (!address)
+        return false;
+    const normalized = normalizeAddress(address);
+    return /^0x[0-9a-f]{40}$/.test(normalized);
+}
+/**
+ * Check if two addresses are the same (case-insensitive, prefix-aware).
+ */
+export function addressEqual(a, b) {
+    return normalizeAddress(a) === normalizeAddress(b);
+}
+//# sourceMappingURL=address.js.map

package/dist/utils/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../../src/utils/address.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,IAAI,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC;IAC7B,IAAI,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACjC,UAAU,GAAG,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC7C,OAAO,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC7C,OAAO,kBAAkB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,CAAS,EAAE,CAAS;IAC/C,OAAO,gBAAgB,CAAC,CAAC,CAAC,KAAK,gBAAgB,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC"}

package/dist/utils/format.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Formatting utilities for blockchain values.
+ */
+/** Format XDC amount from wei to human-readable string */
+export declare function formatXDC(weiAmount: bigint): string;
+/** Format native token amount from wei (generic, no unit suffix) */
+export declare function formatWei(weiAmount: bigint, decimals?: number): string;
+/** Parse hex string to number */
+export declare function parseHexOrDecimal(value: string | number): number;
+/** Convert number to hex string with 0x prefix */
+export declare function toHex(value: number): string;
+/** Get current date string (YYYY-MM-DD) */
+export declare function getCurrentDateString(): string;
+/** Get current Unix timestamp in seconds */
+export declare function nowSeconds(): number;
+/** Truncate an address for display: 0x1234...abcd */
+export declare function shortAddress(address: string): string;
+/** Sleep helper */
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=format.d.ts.map

package/dist/utils/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED,oEAAoE;AACpE,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAW,GAAG,MAAM,CAK1E;AAED,iCAAiC;AACjC,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAMhE;AAED,kDAAkD;AAClD,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,2CAA2C;AAC3C,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED,4CAA4C;AAC5C,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED,mBAAmB;AACnB,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/utils/format.js

@@ -0,0 +1,53 @@
+/**
+ * Formatting utilities for blockchain values.
+ */
+/** Format XDC amount from wei to human-readable string */
+export function formatXDC(weiAmount) {
+    const xdc = Number(weiAmount) / 1e18;
+    if (xdc >= 1_000_000)
+        return `${(xdc / 1_000_000).toFixed(2)}M XDC`;
+    if (xdc >= 1_000)
+        return `${(xdc / 1_000).toFixed(2)}K XDC`;
+    return `${xdc.toFixed(2)} XDC`;
+}
+/** Format native token amount from wei (generic, no unit suffix) */
+export function formatWei(weiAmount, decimals = 18) {
+    const value = Number(weiAmount) / Math.pow(10, decimals);
+    if (value >= 1_000_000)
+        return `${(value / 1_000_000).toFixed(2)}M`;
+    if (value >= 1_000)
+        return `${(value / 1_000).toFixed(2)}K`;
+    return value.toFixed(4);
+}
+/** Parse hex string to number */
+export function parseHexOrDecimal(value) {
+    if (typeof value === 'number')
+        return value;
+    if (value.startsWith('0x') || value.startsWith('0X')) {
+        return parseInt(value, 16);
+    }
+    return parseInt(value, 10);
+}
+/** Convert number to hex string with 0x prefix */
+export function toHex(value) {
+    return '0x' + value.toString(16);
+}
+/** Get current date string (YYYY-MM-DD) */
+export function getCurrentDateString() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** Get current Unix timestamp in seconds */
+export function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+/** Truncate an address for display: 0x1234...abcd */
+export function shortAddress(address) {
+    if (!address || address.length < 10)
+        return address;
+    return `${address.slice(0, 6)}...${address.slice(-4)}`;
+}
+/** Sleep helper */
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=format.js.map

package/dist/utils/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,0DAA0D;AAC1D,MAAM,UAAU,SAAS,CAAC,SAAiB;IACzC,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;IACrC,IAAI,GAAG,IAAI,SAAS;QAAE,OAAO,GAAG,CAAC,GAAG,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IACpE,IAAI,GAAG,IAAI,KAAK;QAAE,OAAO,GAAG,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IAC5D,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;AACjC,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,SAAS,CAAC,SAAiB,EAAE,WAAmB,EAAE;IAChE,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IACzD,IAAI,KAAK,IAAI,SAAS;QAAE,OAAO,GAAG,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IACpE,IAAI,KAAK,IAAI,KAAK;QAAE,OAAO,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IAC5D,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC1B,CAAC;AAED,iCAAiC;AACjC,MAAM,UAAU,iBAAiB,CAAC,KAAsB;IACtD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACrD,OAAO,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,KAAK,CAAC,KAAa;IACjC,OAAO,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AACnC,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,UAAU;IACxB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;AACvC,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,OAAO,CAAC;IACpD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACzD,CAAC;AAED,mBAAmB;AACnB,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Simple structured logger — no external dependencies.
+ * Supports log levels: debug, info, warn, error, silent.
+ */
+import type { LogLevel } from '../types/index.js';
+export declare class Logger {
+    private readonly context;
+    private readonly level;
+    constructor(context: string, level?: LogLevel);
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+    private log;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAmBlD,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,QAAiB;IAKrD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAM5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAM3C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAM3C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAM5C,OAAO,CAAC,GAAG;CAUZ"}