lovewebconnection 0.0.0-stage → 0.2.1

package/dist/presets-summary.d.ts

@@ -0,0 +1,17 @@
+import type { toPresetsJson } from "./presets.ts";
+type PresetsJson = ReturnType<typeof toPresetsJson>;
+export interface PresetsSummary {
+    /** Markdown for the CI run summary. */
+    markdown: string;
+    /** One line per failover, escaped and ready for a ::warning:: annotation. */
+    warnings: string[];
+}
+/** GitHub decodes annotation data through these escapes. */
+export declare function escapeAnnotation(value: string): string;
+/**
+ * Summarize a `lwc presets --json` report for a CI run. Failovers are called out
+ * by name rather than left in the `via` column, so a run that quietly fell back
+ * to a backup is visible in the run history.
+ */
+export declare function summarizePresets(report: PresetsJson): PresetsSummary;
+export {};

package/dist/presets-summary.js

@@ -0,0 +1,55 @@
+/** Table cells cannot hold pipes or newlines. */
+function cell(value) {
+    return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+/** GitHub decodes annotation data through these escapes. */
+export function escapeAnnotation(value) {
+    return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+function failoverLine(endpoint) {
+    return `${endpoint.preset}: primary ${endpoint.primaryHost} failed (${endpoint.primaryError ?? "unknown error"}); answered by ${endpoint.rpcHost}`;
+}
+/**
+ * Summarize a `lwc presets --json` report for a CI run. Failovers are called out
+ * by name rather than left in the `via` column, so a run that quietly fell back
+ * to a backup is visible in the run history.
+ */
+export function summarizePresets(report) {
+    const failovers = report.endpoints.filter((endpoint) => endpoint.ok && endpoint.viaFallback);
+    const failures = report.endpoints.filter((endpoint) => !endpoint.ok);
+    const headline = failovers.length === 0
+        ? `**${report.healthy} of ${report.total} endpoints healthy** — every endpoint answered on its primary.`
+        : `**${report.healthy} of ${report.total} endpoints healthy**, ${failovers.length} served by a backup.`;
+    const rows = report.endpoints.map((endpoint) => {
+        const status = endpoint.ok ? "healthy" : "failed";
+        const latency = endpoint.ok && endpoint.latencyMs !== null ? `${endpoint.latencyMs} ms` : "—";
+        const block = endpoint.blockNumber ?? "—";
+        const via = endpoint.ok ? (endpoint.viaFallback ? "backup" : "primary") : "—";
+        return `| \`${endpoint.preset}\` | ${endpoint.chainId} | ${endpoint.nativeSymbol} | ${status} | ${latency} | ${block} | ${via} | \`${cell(endpoint.rpcHost)}\` |`;
+    });
+    const lines = [
+        "### Built-in preset health",
+        "",
+        headline,
+        "",
+        "| preset | chain | native | status | latency | block | via | endpoint |",
+        "| --- | --- | --- | --- | --- | --- | --- | --- |",
+        ...rows,
+    ];
+    if (failovers.length > 0) {
+        lines.push("", "#### Failovers", "");
+        for (const endpoint of failovers) {
+            lines.push(`- \`${endpoint.preset}\` — primary \`${endpoint.primaryHost}\` failed: ${cell(endpoint.primaryError ?? "unknown error")}; answered by \`${endpoint.rpcHost}\``);
+        }
+    }
+    if (failures.length > 0) {
+        lines.push("", "#### Failures", "");
+        for (const endpoint of failures) {
+            lines.push(`- \`${endpoint.preset}\` — ${cell(endpoint.error ?? "unknown error")}`);
+        }
+    }
+    return {
+        markdown: lines.join("\n"),
+        warnings: failovers.map((endpoint) => escapeAnnotation(failoverLine(endpoint))),
+    };
+}

package/dist/presets.d.ts

@@ -0,0 +1,59 @@
+import type { PublicClient } from "viem";
+import { type ChainConfig, type ChainPreset } from "./chain.ts";
+export declare const DEFAULT_PROBE_TIMEOUT_MS = 10000;
+export declare class PresetsArgError extends Error {
+    constructor(message: string);
+}
+export interface PresetProbeResult {
+    preset: string;
+    chainId: number;
+    nativeSymbol: string;
+    /** Host that answered: the backup endpoint when the primary could not. */
+    rpcHost: string;
+    /** Host of the configured (primary) endpoint, for failover reporting. */
+    primaryHost: string;
+    /** True when the primary failed and the backup answered instead. */
+    viaFallback: boolean;
+    /** Why the primary was skipped, when viaFallback is true. */
+    primaryError: string | null;
+    ok: boolean;
+    latencyMs: number | null;
+    blockNumber: bigint | null;
+    error: string | null;
+}
+export interface PresetsReport {
+    total: number;
+    healthy: number;
+    failed: number;
+    endpoints: PresetProbeResult[];
+}
+export interface PresetProbeDeps {
+    /** Defaults to the real viem client; tests inject a stub. */
+    clientFor?: (config: ChainConfig) => PublicClient;
+    timeoutMs?: number;
+    /** Defaults to the built-in table; tests can narrow it. */
+    presets?: Record<string, ChainPreset>;
+}
+/**
+ * Probe every built-in preset in parallel and report each one separately, so a
+ * single dead endpoint cannot hide the others. A failed probe is data here, not
+ * an exception: the caller decides what an unhealthy endpoint means.
+ */
+export declare function probePresets(deps?: PresetProbeDeps): Promise<PresetsReport>;
+export declare function formatPresets(report: PresetsReport): string;
+export declare function toPresetsJson(report: PresetsReport): {
+    total: number;
+    healthy: number;
+    failed: number;
+    endpoints: Array<Omit<PresetProbeResult, "blockNumber"> & {
+        blockNumber: string | null;
+    }>;
+};
+/**
+ * `lwc presets` takes --json, --timeout, and --history; --chain is meaningless
+ * here, since the command probes every preset.
+ */
+export declare function parsePresetsArgs(argv: string[]): {
+    timeoutMs: number;
+    historyPath: string | null;
+};

package/dist/presets.js

@@ -0,0 +1,181 @@
+import { CHAIN_PRESETS, ChainMismatchError, buildClient, probeWithFallback, } from "./chain.js";
+export const DEFAULT_PROBE_TIMEOUT_MS = 10_000;
+const MIN_PROBE_TIMEOUT_MS = 250;
+const MAX_PROBE_TIMEOUT_MS = 120_000;
+export class PresetsArgError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PresetsArgError";
+    }
+}
+function describeFailure(error) {
+    if (error instanceof ChainMismatchError)
+        return `chain mismatch: ${error.message}`;
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+function hostOf(rpcUrl) {
+    try {
+        return new URL(rpcUrl).host;
+    }
+    catch {
+        return "<invalid>";
+    }
+}
+/**
+ * Probe every built-in preset in parallel and report each one separately, so a
+ * single dead endpoint cannot hide the others. A failed probe is data here, not
+ * an exception: the caller decides what an unhealthy endpoint means.
+ */
+export async function probePresets(deps = {}) {
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    const clientFor = deps.clientFor ?? buildClient;
+    const presets = deps.presets ?? CHAIN_PRESETS;
+    const names = Object.keys(presets).sort();
+    const endpoints = await Promise.all(names.map(async (name) => {
+        const preset = presets[name];
+        const config = {
+            chainId: preset.chainId,
+            name: preset.name,
+            rpcUrl: preset.rpcUrl,
+            fallbackRpcUrl: preset.fallbackRpcUrl,
+            nativeCurrency: {
+                name: preset.nativeSymbol,
+                symbol: preset.nativeSymbol,
+                decimals: 18,
+            },
+            authHeader: null,
+            timeoutMs,
+            preset: preset.name,
+        };
+        const base = {
+            preset: name,
+            chainId: preset.chainId,
+            nativeSymbol: preset.nativeSymbol,
+            primaryHost: hostOf(preset.rpcUrl),
+        };
+        try {
+            // The backup endpoint is part of the preset, so a dead primary still
+            // reports the chain as reachable and says which endpoint answered.
+            const outcome = await probeWithFallback(clientFor, config);
+            return {
+                ...base,
+                rpcHost: outcome.health.rpcHost,
+                viaFallback: outcome.usedFallback,
+                primaryError: outcome.primaryError,
+                ok: true,
+                latencyMs: outcome.health.latencyMs,
+                blockNumber: outcome.health.blockNumber,
+                error: null,
+            };
+        }
+        catch (error) {
+            return {
+                ...base,
+                rpcHost: hostOf(preset.rpcUrl),
+                viaFallback: false,
+                primaryError: null,
+                ok: false,
+                latencyMs: null,
+                blockNumber: null,
+                error: describeFailure(error),
+            };
+        }
+    }));
+    const healthy = endpoints.filter((endpoint) => endpoint.ok).length;
+    return {
+        total: endpoints.length,
+        healthy,
+        failed: endpoints.length - healthy,
+        endpoints,
+    };
+}
+export function formatPresets(report) {
+    const rows = report.endpoints.map((endpoint) => [
+        endpoint.preset,
+        String(endpoint.chainId),
+        endpoint.ok ? "healthy" : "failed",
+        endpoint.ok && endpoint.latencyMs !== null ? `${endpoint.latencyMs} ms` : "—",
+        endpoint.ok && endpoint.blockNumber !== null ? String(endpoint.blockNumber) : "—",
+        endpoint.ok ? (endpoint.viaFallback ? "backup" : "primary") : "—",
+    ]);
+    const headers = ["preset", "chain", "status", "latency", "block", "via"];
+    const widths = headers.map((header, column) => Math.max(header.length, ...rows.map((row) => row[column].length)));
+    const line = (cells) => `  ${cells.map((cell, column) => cell.padEnd(widths[column])).join("  ").trimEnd()}`;
+    const lines = ["lwc — built-in presets", "", line(headers), ...rows.map(line)];
+    for (const endpoint of report.endpoints) {
+        if (!endpoint.ok) {
+            lines.push(`  ${endpoint.preset}: ${endpoint.error ?? "unknown error"}`);
+        }
+        else if (endpoint.viaFallback) {
+            lines.push(`  ${endpoint.preset}: primary failed (${endpoint.primaryError ?? "unknown error"}); answered by ${endpoint.rpcHost}`);
+        }
+    }
+    lines.push("", `${report.healthy} of ${report.total} endpoints healthy`);
+    return lines.join("\n");
+}
+export function toPresetsJson(report) {
+    return {
+        total: report.total,
+        healthy: report.healthy,
+        failed: report.failed,
+        endpoints: report.endpoints.map((endpoint) => ({
+            ...endpoint,
+            blockNumber: endpoint.blockNumber === null ? null : endpoint.blockNumber.toString(),
+        })),
+    };
+}
+function parseTimeout(raw) {
+    if (!/^\d+$/.test(raw)) {
+        throw new PresetsArgError(`--timeout must be whole milliseconds, got "${raw}".`);
+    }
+    const timeoutMs = Number(raw);
+    if (timeoutMs < MIN_PROBE_TIMEOUT_MS || timeoutMs > MAX_PROBE_TIMEOUT_MS) {
+        throw new PresetsArgError(`--timeout must be between ${MIN_PROBE_TIMEOUT_MS} and ${MAX_PROBE_TIMEOUT_MS} ms.`);
+    }
+    return timeoutMs;
+}
+/**
+ * `lwc presets` takes --json, --timeout, and --history; --chain is meaningless
+ * here, since the command probes every preset.
+ */
+export function parsePresetsArgs(argv) {
+    let timeoutMs = DEFAULT_PROBE_TIMEOUT_MS;
+    let historyPath = null;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index] ?? "";
+        if (arg === "--json")
+            continue;
+        if (arg === "--timeout") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new PresetsArgError("--timeout requires a value.");
+            timeoutMs = parseTimeout(value);
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--timeout=")) {
+            timeoutMs = parseTimeout(arg.slice("--timeout=".length));
+            continue;
+        }
+        if (arg === "--history") {
+            const value = argv[index + 1];
+            if (!value || value.startsWith("--")) {
+                throw new PresetsArgError("--history requires a file path.");
+            }
+            historyPath = value;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--history=")) {
+            const value = arg.slice("--history=".length);
+            if (!value)
+                throw new PresetsArgError("--history requires a file path.");
+            historyPath = value;
+            continue;
+        }
+        throw new PresetsArgError(`unexpected argument "${arg}".`);
+    }
+    return { timeoutMs, historyPath };
+}

package/dist/prices.d.ts

@@ -0,0 +1,63 @@
+import type { Address } from "viem";
+export interface PriceQuote {
+    price: number;
+    symbol: string | null;
+    /** Source timestamp in epoch seconds, when it provides one. */
+    timestamp: number | null;
+}
+export interface PriceBook {
+    /** Lowercased token address → quote. A token the feed cannot price is absent. */
+    tokens: Map<string, PriceQuote>;
+    native: PriceQuote | null;
+    /** Why the last refresh failed; null when it succeeded. */
+    error: string | null;
+}
+export interface PriceSourceOptions {
+    /** DefiLlama chain slug, e.g. "xlayer". */
+    chainSlug?: string;
+    /** Coin id used for the native balance. */
+    nativeId?: string;
+    baseUrl?: string;
+    /** Quotes older than this are refreshed. Default 60 s. */
+    ttlMs?: number;
+    timeoutMs?: number;
+    /** Injected for tests; defaults to Date.now. */
+    now?: () => number;
+    /** Injected for tests; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export declare const DEFAULT_PRICE_BASE_URL = "https://coins.llama.fi";
+export declare const DEFAULT_PRICE_TTL_MS = 60000;
+/** OKB is the native currency of X Layer; DefiLlama prices it by CoinGecko id. */
+export declare const DEFAULT_NATIVE_PRICE_ID = "coingecko:okb";
+/** DefiLlama chain slug for a chain id; null when this kit has no feed for it. */
+export declare function priceChainSlug(chainId: number): string | null;
+/**
+ * USD value of a base-unit balance. Null when the balance, its decimals, or the
+ * price is missing, so an unpriced asset never counts as zero.
+ */
+export declare function usdValue(balance: bigint | null, decimals: number | null, price: number | null): number | null;
+/**
+ * Batched USD prices from DefiLlama's free coins API, cached for a TTL so a
+ * watch loop polling every few seconds makes at most one price request a minute.
+ * A refresh covers every requested token plus the native balance in one call.
+ * Failures never throw: the last known quotes are kept and `error` says why.
+ */
+export declare class PriceSource {
+    private readonly chainSlug;
+    private readonly nativeId;
+    private readonly baseUrl;
+    private readonly ttlMs;
+    private readonly timeoutMs;
+    private readonly now;
+    private readonly fetchImpl;
+    private readonly tokenQuotes;
+    private nativeQuote;
+    private error;
+    constructor(options?: PriceSourceOptions);
+    prices(tokens: Address[]): Promise<PriceBook>;
+    private refresh;
+    /** Remember that these assets were checked, so a failure waits for the TTL. */
+    private markChecked;
+    private quoteOf;
+}

package/dist/prices.js

@@ -0,0 +1,154 @@
+export const DEFAULT_PRICE_BASE_URL = "https://coins.llama.fi";
+export const DEFAULT_PRICE_TTL_MS = 60_000;
+/** OKB is the native currency of X Layer; DefiLlama prices it by CoinGecko id. */
+export const DEFAULT_NATIVE_PRICE_ID = "coingecko:okb";
+const DEFAULT_TIMEOUT_MS = 5000;
+/** DefiLlama chain slug for a chain id; null when this kit has no feed for it. */
+export function priceChainSlug(chainId) {
+    return chainId === 196 ? "xlayer" : null;
+}
+/**
+ * USD value of a base-unit balance. Null when the balance, its decimals, or the
+ * price is missing, so an unpriced asset never counts as zero.
+ */
+export function usdValue(balance, decimals, price) {
+    if (balance === null || decimals === null || price === null)
+        return null;
+    if (!Number.isFinite(price) || decimals < 0 || decimals > 36)
+        return null;
+    return (Number(balance) / 10 ** decimals) * price;
+}
+function objectOf(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function numberField(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function stringField(value) {
+    return typeof value === "string" ? value : null;
+}
+function describePriceError(error) {
+    if (error instanceof Error) {
+        const short = error.shortMessage;
+        if (typeof short === "string" && short.length > 0)
+            return short;
+        return error.message;
+    }
+    return String(error);
+}
+/**
+ * Batched USD prices from DefiLlama's free coins API, cached for a TTL so a
+ * watch loop polling every few seconds makes at most one price request a minute.
+ * A refresh covers every requested token plus the native balance in one call.
+ * Failures never throw: the last known quotes are kept and `error` says why.
+ */
+export class PriceSource {
+    chainSlug;
+    nativeId;
+    baseUrl;
+    ttlMs;
+    timeoutMs;
+    now;
+    fetchImpl;
+    tokenQuotes = new Map();
+    nativeQuote = null;
+    error = null;
+    constructor(options = {}) {
+        this.chainSlug = options.chainSlug ?? "xlayer";
+        this.nativeId = options.nativeId ?? DEFAULT_NATIVE_PRICE_ID;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_PRICE_BASE_URL).replace(/\/+$/, "");
+        this.ttlMs = options.ttlMs ?? DEFAULT_PRICE_TTL_MS;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.now = options.now ?? (() => Date.now());
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async prices(tokens) {
+        const unique = [...new Map(tokens.map((token) => [token.toLowerCase(), token])).values()];
+        const now = this.now();
+        const stale = unique.some((token) => {
+            const cached = this.tokenQuotes.get(token.toLowerCase());
+            return cached === undefined || now - cached.at >= this.ttlMs;
+        });
+        const nativeStale = this.nativeQuote === null || now - this.nativeQuote.at >= this.ttlMs;
+        if (stale || nativeStale)
+            await this.refresh(unique);
+        const quotes = new Map();
+        for (const token of unique) {
+            const cached = this.tokenQuotes.get(token.toLowerCase());
+            if (cached?.quote)
+                quotes.set(token.toLowerCase(), cached.quote);
+        }
+        return {
+            tokens: quotes,
+            native: this.nativeQuote?.quote ?? null,
+            error: this.error,
+        };
+    }
+    async refresh(tokens) {
+        const keys = [
+            ...tokens.map((token) => `${this.chainSlug}:${token.toLowerCase()}`),
+            this.nativeId,
+        ];
+        const url = `${this.baseUrl}/prices/current/${keys.join(",")}`;
+        try {
+            const response = await this.fetchImpl(url, {
+                signal: AbortSignal.timeout(this.timeoutMs),
+                headers: { accept: "application/json" },
+            });
+            if (!response.ok) {
+                this.error = `HTTP ${response.status}`;
+                this.markChecked(tokens, this.now());
+                return;
+            }
+            const payload = (await response.json());
+            const coins = objectOf(payload.coins);
+            if (coins === null) {
+                this.error = "unexpected response from the price feed";
+                this.markChecked(tokens, this.now());
+                return;
+            }
+            // Keys come back in the feed's casing, so compare them lowercased.
+            const byKey = new Map();
+            for (const [key, value] of Object.entries(coins)) {
+                byKey.set(key.toLowerCase(), objectOf(value));
+            }
+            const at = this.now();
+            for (const token of tokens) {
+                const raw = byKey.get(`${this.chainSlug}:${token.toLowerCase()}`.toLowerCase()) ?? null;
+                const price = numberField(raw?.price);
+                this.tokenQuotes.set(token.toLowerCase(), {
+                    quote: price === null ? null : this.quoteOf(price, raw),
+                    at,
+                });
+            }
+            const nativeRaw = byKey.get(this.nativeId.toLowerCase()) ?? null;
+            const nativePrice = numberField(nativeRaw?.price);
+            this.nativeQuote = {
+                quote: nativePrice === null ? null : this.quoteOf(nativePrice, nativeRaw),
+                at,
+            };
+            this.error = null;
+        }
+        catch (error) {
+            this.error = describePriceError(error);
+            this.markChecked(tokens, this.now());
+        }
+    }
+    /** Remember that these assets were checked, so a failure waits for the TTL. */
+    markChecked(tokens, at) {
+        for (const token of tokens) {
+            const key = token.toLowerCase();
+            this.tokenQuotes.set(key, { quote: this.tokenQuotes.get(key)?.quote ?? null, at });
+        }
+        this.nativeQuote = { quote: this.nativeQuote?.quote ?? null, at };
+    }
+    quoteOf(price, raw) {
+        return {
+            price,
+            symbol: stringField(raw?.symbol),
+            timestamp: numberField(raw?.timestamp),
+        };
+    }
+}

package/dist/rotate.d.ts

@@ -0,0 +1,19 @@
+export interface RotatingLogOptions {
+    path: string;
+    /** Rotate before a write would push the file past this many bytes; 0 disables it. */
+    maxBytes: number;
+}
+/**
+ * Append-only NDJSON writer with one size-triggered backup. When the next line
+ * would exceed `maxBytes`, the active file is renamed to `<path>.1` (replacing
+ * the previous backup) and a fresh file starts, so the log never grows past the
+ * limit plus a single line. A JSON line is never split.
+ */
+export declare class RotatingLog {
+    readonly path: string;
+    readonly maxBytes: number;
+    private bytes;
+    constructor(options: RotatingLogOptions);
+    append(text: string): void;
+    private rotate;
+}

package/dist/rotate.js

@@ -0,0 +1,34 @@
+import { appendFileSync, existsSync, renameSync, rmSync, statSync } from "node:fs";
+/**
+ * Append-only NDJSON writer with one size-triggered backup. When the next line
+ * would exceed `maxBytes`, the active file is renamed to `<path>.1` (replacing
+ * the previous backup) and a fresh file starts, so the log never grows past the
+ * limit plus a single line. A JSON line is never split.
+ */
+export class RotatingLog {
+    path;
+    maxBytes;
+    bytes;
+    constructor(options) {
+        this.path = options.path;
+        this.maxBytes = options.maxBytes;
+        this.bytes = existsSync(this.path) ? statSync(this.path).size : 0;
+    }
+    append(text) {
+        const line = text.endsWith("\n") ? text : `${text}\n`;
+        const size = Buffer.byteLength(line, "utf8");
+        // Rotating an empty file would just rename a zero-byte file, and a single
+        // line larger than the limit still has to be written somewhere.
+        if (this.maxBytes > 0 && this.bytes > 0 && this.bytes + size > this.maxBytes) {
+            this.rotate();
+        }
+        appendFileSync(this.path, line);
+        this.bytes += size;
+    }
+    rotate() {
+        const backup = `${this.path}.1`;
+        rmSync(backup, { force: true });
+        renameSync(this.path, backup);
+        this.bytes = 0;
+    }
+}

package/dist/scan.d.ts

@@ -0,0 +1,81 @@
+import { type Address, type PublicClient } from "viem";
+import type { ChainConfig } from "./chain.ts";
+import { type BalancesOptions, type CacheStats, type ChunkStatus, type RecoverySummary, type TokenBalance } from "./balances.ts";
+export declare class ScanArgError extends Error {
+    constructor(message: string);
+}
+export interface ScanArgs {
+    owners: Address[];
+    tokens: Address[];
+    /** Lowercased token address → label from the token list file. */
+    labels: Map<string, string>;
+    /** `null` prints the table; "-" prints CSV; anything else is a file path. */
+    csvPath: string | null;
+    /** Tokens per Multicall3 request. */
+    batchSize: number;
+    /** Fixed sub-call cap per Multicall3 request, independent of cache state. */
+    maxSubCalls: number | null;
+    /** Exit non-zero when any chunk needed a retry or individual fallback. */
+    failOnRetry: boolean;
+    /** Suppress per-chunk progress on stderr; reports and JSON are unchanged. */
+    quiet: boolean;
+    /** Refresh cached metadata older than this many milliseconds. */
+    maxCacheAgeMs: number | null;
+    /** Warn when cached metadata is older than this many milliseconds; never refreshes. */
+    staleAfterMs: number | null;
+    /** Non-fatal label conflicts found while merging token sources. */
+    warnings: string[];
+}
+export interface ScanRow {
+    owner: Address;
+    native: bigint;
+    balances: (bigint | null)[];
+}
+export interface ScanChunkReport {
+    owner: Address;
+    index: number;
+    total: number;
+    tokens: number;
+    status: ChunkStatus;
+    error: string | null;
+    /** Tokens from this chunk read individually. */
+    individual: Address[];
+}
+export interface ScanFallback {
+    owner: Address;
+    token: Address;
+    symbol: string;
+    label: string | null;
+    /** 1-based chunk position. */
+    chunk: number;
+    chunks: number;
+    error: string | null;
+}
+export interface ScanReport {
+    chainId: number;
+    chainName: string;
+    blockNumber: bigint;
+    nativeSymbol: string;
+    nativeDecimals: number;
+    owners: Address[];
+    tokens: TokenBalance[];
+    /** Tokens per Multicall3 request selected for the owner reads. */
+    batchSize: number;
+    /** Total Multicall3 chunks attempted across owners. */
+    chunkCount: number;
+    rows: ScanRow[];
+    warnings: string[];
+    chunks: ScanChunkReport[];
+    /** Every token that had to be read individually, with its owner and chunk. */
+    fallbacks: ScanFallback[];
+    /** First-attempt failures and retry outcomes across owners. */
+    recovery: RecoverySummary;
+    /** Metadata cache hits and misses for this scan. */
+    cache: CacheStats;
+}
+export declare function parseScanArgs(argv: string[]): ScanArgs;
+export declare function scanBalances(client: PublicClient, config: ChainConfig, owners: Address[], tokens: Address[], options?: BalancesOptions): Promise<ScanReport>;
+export declare function csvCell(value: string): string;
+export declare function scanCsv(report: ScanReport): string;
+export declare function formatScan(report: ScanReport): string;
+export declare function toScanJson(report: ScanReport): Record<string, unknown>;