lovewebconnection 0.0.0-stage → 0.2.1

package/dist/sessions.js

@@ -0,0 +1,515 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { percentile } from "./metrics.js";
+import { csvCell } from "./scan.js";
+export class SessionsArgError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SessionsArgError";
+    }
+}
+const SINCE_UNITS_MS = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+/** `--since` takes an ISO timestamp or a span relative to now, e.g. `24h`. */
+function parseSince(raw) {
+    const relative = /^(\d+)([smhd])$/.exec(raw);
+    if (relative) {
+        const amount = Number(relative[1]);
+        const unit = SINCE_UNITS_MS[relative[2]];
+        return Date.now() - amount * unit;
+    }
+    const parsed = Date.parse(raw);
+    if (!Number.isFinite(parsed)) {
+        throw new SessionsArgError(`--since must be an ISO timestamp or a span like 24h, got "${raw}".`);
+    }
+    return parsed;
+}
+export function parseSessionsArgs(argv) {
+    const positional = [];
+    let since = null;
+    const sessionPrefixes = [];
+    let csvPath = null;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index] ?? "";
+        const readValue = (flag) => {
+            const value = argv[index + 1];
+            if (!value)
+                throw new SessionsArgError(`${flag} requires a value.`);
+            index += 1;
+            return value;
+        };
+        if (arg === "--since" || arg.startsWith("--since=")) {
+            const value = arg.startsWith("--since=") ? arg.slice("--since=".length) : readValue("--since");
+            since = parseSince(value);
+        }
+        else if (arg === "--session" || arg.startsWith("--session=")) {
+            const value = arg.startsWith("--session=") ? arg.slice("--session=".length) : readValue("--session");
+            if (!value)
+                throw new SessionsArgError("--session requires a prefix.");
+            sessionPrefixes.push(value);
+        }
+        else if (arg === "--csv") {
+            const value = argv[index + 1];
+            if (!value || (value.startsWith("-") && value !== "-")) {
+                throw new SessionsArgError("--csv requires a path, or - for stdout.");
+            }
+            csvPath = value;
+            index += 1;
+        }
+        else if (arg.startsWith("--csv=")) {
+            const value = arg.slice("--csv=".length);
+            if (!value)
+                throw new SessionsArgError("--csv requires a path, or - for stdout.");
+            csvPath = value;
+        }
+        else if (arg.startsWith("-")) {
+            // --json and any other global flags are handled by the CLI.
+            continue;
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    const [path] = positional;
+    if (!path) {
+        throw new SessionsArgError("A watch log path is required: lwc sessions <log.ndjson>");
+    }
+    if (positional.length > 1) {
+        throw new SessionsArgError(`Unexpected extra argument: ${positional[1]}.`);
+    }
+    return { path, since, sessionPrefixes, csvPath };
+}
+export function readWatchLog(path) {
+    if (!existsSync(path)) {
+        throw new SessionsArgError(`watch log not found: ${path}`);
+    }
+    return readFileSync(path, "utf8");
+}
+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 bigintField(value) {
+    if (typeof value === "string" && /^\d+$/.test(value))
+        return BigInt(value);
+    if (typeof value === "number" && Number.isSafeInteger(value))
+        return BigInt(value);
+    return null;
+}
+function timeField(value) {
+    if (typeof value !== "string")
+        return null;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? ms : null;
+}
+function latencyStats(values) {
+    if (values.length === 0)
+        return { count: 0, p50: 0, p95: 0, max: 0 };
+    const sorted = [...values].sort((a, b) => a - b);
+    return {
+        count: sorted.length,
+        p50: percentile(sorted, 50),
+        p95: percentile(sorted, 95),
+        max: sorted[sorted.length - 1] ?? 0,
+    };
+}
+function blockTimeStats(values) {
+    if (values.length === 0)
+        return { count: 0, medianSeconds: 0, minSeconds: 0, maxSeconds: 0 };
+    const sorted = [...values].sort((a, b) => a - b);
+    return {
+        count: sorted.length,
+        medianSeconds: percentile(sorted, 50),
+        minSeconds: sorted[0] ?? 0,
+        maxSeconds: sorted[sorted.length - 1] ?? 0,
+    };
+}
+function summaryOf(lines) {
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        if (lines[index]?.event === "summary")
+            return lines[index] ?? null;
+    }
+    return null;
+}
+function buildSession(id, lines) {
+    const start = lines.find((line) => line.event === "start") ?? null;
+    const summary = summaryOf(lines);
+    const advances = lines.filter((line) => line.event === "advance");
+    const holds = lines.filter((line) => line.event === "hold");
+    const latencyValues = [...advances, ...holds]
+        .map((line) => numberField(line.latencyMs))
+        .filter((value) => value !== null);
+    // Block time is the gap between consecutive advances that moved the head,
+    // which is what the watch run itself samples.
+    const blockTimes = [];
+    for (let index = 1; index < advances.length; index += 1) {
+        const delta = bigintField(advances[index]?.delta);
+        const at = timeField(advances[index]?.at);
+        const previousAt = timeField(advances[index - 1]?.at);
+        if (delta !== null && delta > 0n && at !== null && previousAt !== null) {
+            blockTimes.push(Math.max(0, (at - previousAt) / 1000));
+        }
+    }
+    const startTime = timeField(start?.at);
+    const eventTimes = lines
+        .map((line) => timeField(line.at))
+        .filter((value) => value !== null);
+    const firstEventTime = eventTimes.length > 0 ? Math.min(...eventTimes) : null;
+    const lastEventTime = eventTimes.length > 0 ? Math.max(...eventTimes) : null;
+    const startedAt = startTime ?? firstEventTime;
+    const summaryDuration = summary === null ? null : numberField(summary.durationMs);
+    const durationMs = summaryDuration ??
+        (startedAt !== null && lastEventTime !== null ? Math.max(0, lastEventTime - startedAt) : 0);
+    const blockNumbers = [...advances, ...holds]
+        .map((line) => bigintField(line.blockNumber))
+        .filter((value) => value !== null);
+    const firstBlock = summary === null ? null : bigintField(summary.firstBlock);
+    const lastBlock = summary === null ? null : bigintField(summary.lastBlock);
+    const chainRaw = start === null ? null : objectOf(start.chain);
+    const chainId = chainRaw === null ? null : numberField(chainRaw.id);
+    const chainName = chainRaw !== null && typeof chainRaw.name === "string" ? chainRaw.name : null;
+    const firstBlockNumber = blockNumbers[0] ?? null;
+    const lastBlockNumber = blockNumbers[blockNumbers.length - 1] ?? null;
+    const rawFirst = firstBlock ?? firstBlockNumber;
+    const rawLast = lastBlock ?? lastBlockNumber;
+    const advancedBy = summary === null
+        ? rawFirst !== null && rawLast !== null
+            ? rawLast - rawFirst
+            : 0n
+        : (bigintField(summary.advancedBy) ?? 0n);
+    return {
+        id,
+        chain: chainId === null ? null : { id: chainId, name: chainName ?? "?" },
+        endpoint: start !== null && typeof start.endpoint === "string" ? start.endpoint : null,
+        state: summary === null ? "partial" : summary.aborted === true ? "aborted" : "complete",
+        startedAt,
+        endedAt: startedAt === null ? lastEventTime : startedAt + durationMs,
+        durationMs,
+        samples: (summary === null ? null : numberField(summary.samples)) ?? advances.length + holds.length,
+        latency: latencyStats(latencyValues),
+        blockTime: blockTimeStats(blockTimes),
+        stalls: (summary === null ? null : numberField(summary.stalls)) ??
+            lines.filter((line) => line.event === "stall").length,
+        gasSurges: (summary === null ? null : numberField(summary.gasSurges)) ??
+            lines.filter((line) => line.event === "gas-surge").length,
+        alerts: (summary === null ? null : numberField(summary.alerts)) ??
+            lines.filter((line) => line.event === "alert" || line.event === "balance-alert").length,
+        errors: (summary === null ? null : numberField(summary.errors)) ??
+            lines.filter((line) => line.event === "error").length,
+        chainDrift: summary === null
+            ? lines.some((line) => line.event === "chain-drift")
+            : summary.chainDrift === true,
+        firstBlock: rawFirst,
+        lastBlock: rawLast,
+        advancedBy,
+    };
+}
+function buildEndpoint(endpoint, sessions, latencyValues) {
+    const total = (pick) => sessions.reduce((sum, session) => sum + pick(session), 0);
+    const samples = total((session) => session.samples);
+    const stalls = total((session) => session.stalls);
+    return {
+        endpoint,
+        sessions: sessions.length,
+        samples,
+        latency: latencyStats(latencyValues),
+        stalls,
+        gasSurges: total((session) => session.gasSurges),
+        errors: total((session) => session.errors),
+        stallRate: samples > 0 ? stalls / samples : 0,
+    };
+}
+/**
+ * Group a watch NDJSON log by session id and summarise each run. Latency
+ * percentiles are computed from every poll in the session rather than the
+ * watch run's rolling window, so two sessions with different `--window`
+ * values are still comparable. A session without a `summary` line (killed, or
+ * still running) is kept and marked partial. `filter` narrows a long log before
+ * the comparison: prefixes drop non-matching lines, and `since` drops completed
+ * sessions that started too early.
+ */
+export function summarizeWatchLog(text, filter = {}) {
+    const groups = new Map();
+    const prefixes = filter.sessionPrefixes ?? [];
+    let skippedLines = 0;
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            skippedLines += 1;
+            continue;
+        }
+        const record = objectOf(parsed);
+        const session = record !== null && typeof record.session === "string" ? record.session : null;
+        if (record === null || session === null) {
+            skippedLines += 1;
+            continue;
+        }
+        // A session narrowed away by a prefix is not malformed, so it is not counted.
+        if (prefixes.length > 0 && !prefixes.some((prefix) => session.startsWith(prefix))) {
+            continue;
+        }
+        const existing = groups.get(session);
+        if (existing)
+            existing.push(record);
+        else
+            groups.set(session, [record]);
+    }
+    const sessions = [...groups.entries()]
+        .map(([id, lines]) => buildSession(id, lines))
+        .filter((session) => filter.since == null ||
+        (session.startedAt !== null && session.startedAt >= filter.since));
+    sessions.sort((a, b) => (a.startedAt ?? 0) - (b.startedAt ?? 0));
+    // Pool by RPC host: percentiles over all polls are fairer than averaging the
+    // per-session percentiles, and the host keeps API keys out of the summary.
+    const byEndpoint = new Map();
+    for (const session of sessions) {
+        const lines = groups.get(session.id) ?? [];
+        const start = lines.find((line) => line.event === "start") ?? null;
+        const rawEndpoint = start !== null && typeof start.endpoint === "string" ? start.endpoint : null;
+        const endpoint = rawEndpoint === null ? null : endpointHost(rawEndpoint);
+        const key = endpoint ?? "";
+        let group = byEndpoint.get(key);
+        if (!group) {
+            group = { endpoint, sessions: [], latencies: [] };
+            byEndpoint.set(key, group);
+        }
+        group.sessions.push(session);
+        for (const line of lines) {
+            if (line.event !== "advance" && line.event !== "hold")
+                continue;
+            const latency = numberField(line.latencyMs);
+            if (latency !== null)
+                group.latencies.push(latency);
+        }
+    }
+    const endpoints = [...byEndpoint.values()]
+        .map((group) => buildEndpoint(group.endpoint, group.sessions, group.latencies))
+        .sort((a, b) => b.samples - a.samples ||
+        b.sessions - a.sessions ||
+        (a.endpoint ?? "").localeCompare(b.endpoint ?? ""));
+    return { sessions, endpoints, skippedLines };
+}
+function formatDuration(ms) {
+    const seconds = Math.round(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const rest = seconds % 60;
+    return `${minutes}m${rest.toString().padStart(2, "0")}s`;
+}
+function endpointHost(endpoint) {
+    if (endpoint === null)
+        return "?";
+    try {
+        return new URL(endpoint).host;
+    }
+    catch {
+        return endpoint;
+    }
+}
+function formatStart(at) {
+    if (at === null)
+        return "—";
+    // UTC keeps the table stable regardless of the machine's timezone.
+    return new Date(at).toISOString().slice(5, 19).replace("T", " ");
+}
+function iso(at) {
+    return new Date(at).toISOString();
+}
+const NA = "n/a";
+export function formatSessions(report) {
+    const idWidth = Math.max(7, ...report.sessions.map((session) => session.id.length));
+    const chainWidth = Math.max(5, ...report.sessions.map((session) => session.chain === null ? 1 : `${session.chain.name} (${session.chain.id})`.length));
+    const rpcWidth = Math.max(3, ...report.sessions.map((session) => endpointHost(session.endpoint).length));
+    const partial = report.sessions.filter((session) => session.state === "partial").length;
+    const header = [
+        "session".padEnd(idWidth),
+        "chain".padEnd(chainWidth),
+        "rpc".padEnd(rpcWidth),
+        "started (UTC)".padEnd(15),
+        "duration".padStart(8),
+        "polls".padStart(5),
+        "p50".padStart(5),
+        "p95".padStart(5),
+        "stalls".padStart(6),
+        "surges".padStart(6),
+        "errors".padStart(6),
+        "state".padEnd(8),
+    ].join("  ");
+    const rows = report.sessions.map((session) => {
+        const chain = session.chain === null ? "?" : `${session.chain.name} (${session.chain.id})`;
+        const latency = session.latency;
+        return [
+            session.id.padEnd(idWidth),
+            chain.padEnd(chainWidth),
+            endpointHost(session.endpoint).padEnd(rpcWidth),
+            formatStart(session.startedAt).padEnd(15),
+            formatDuration(session.durationMs).padStart(8),
+            String(session.samples).padStart(5),
+            (latency.count > 0 ? String(latency.p50) : NA).padStart(5),
+            (latency.count > 0 ? String(latency.p95) : NA).padStart(5),
+            String(session.stalls).padStart(6),
+            String(session.gasSurges).padStart(6),
+            String(session.errors).padStart(6),
+            session.state.padEnd(8),
+        ].join("  ");
+    });
+    const lines = [
+        "lwc — watch sessions",
+        "",
+        `  ${"log".padEnd(14)}${report.path}`,
+        `  ${"sessions".padEnd(14)}${report.sessions.length}${partial > 0 ? ` (${partial} partial)` : ""}`,
+    ];
+    if (report.skippedLines > 0) {
+        lines.push(`  ${"skipped".padEnd(14)}${report.skippedLines} malformed line(s)`);
+    }
+    lines.push("", header, ...rows);
+    if (report.endpoints.length > 0) {
+        const hostWidth = Math.max(8, ...report.endpoints.map((item) => (item.endpoint ?? "?").length));
+        const endpointHeader = [
+            "endpoint".padEnd(hostWidth),
+            "sessions".padStart(8),
+            "polls".padStart(6),
+            "p50".padStart(5),
+            "p95".padStart(5),
+            "stalls".padStart(6),
+            "stall rate".padStart(10),
+        ].join("  ");
+        lines.push("", "by endpoint", "", endpointHeader);
+        for (const item of report.endpoints) {
+            const latency = item.latency;
+            lines.push([
+                (item.endpoint ?? "?").padEnd(hostWidth),
+                String(item.sessions).padStart(8),
+                String(item.samples).padStart(6),
+                (latency.count > 0 ? String(latency.p50) : NA).padStart(5),
+                (latency.count > 0 ? String(latency.p95) : NA).padStart(5),
+                String(item.stalls).padStart(6),
+                (item.samples > 0 ? `${(item.stallRate * 100).toFixed(1)}%` : NA).padStart(10),
+            ].join("  "));
+        }
+    }
+    return lines.join("\n");
+}
+export const SESSIONS_CSV_HEADER = [
+    "session",
+    "started_at",
+    "ended_at",
+    "state",
+    "chain",
+    "chain_id",
+    "endpoint",
+    "duration_ms",
+    "samples",
+    "latency_p50_ms",
+    "latency_p95_ms",
+    "latency_max_ms",
+    "block_time_median_s",
+    "block_time_min_s",
+    "block_time_max_s",
+    "stalls",
+    "gas_surges",
+    "alerts",
+    "errors",
+    "chain_drift",
+    "first_block",
+    "last_block",
+    "advanced_by",
+];
+/**
+ * One row per session: identity, chain, RPC endpoint, and the same latency,
+ * block-time, and counter fields as the table. Missing measurements are empty
+ * cells rather than zeroes, so a spreadsheet can tell `no polls` from `0 ms`.
+ */
+export function sessionsCsv(report) {
+    const lines = [SESSIONS_CSV_HEADER.join(",")];
+    for (const session of report.sessions) {
+        const latency = session.latency.count > 0 ? session.latency : null;
+        const blockTime = session.blockTime.count > 0 ? session.blockTime : null;
+        lines.push([
+            session.id,
+            session.startedAt === null ? "" : iso(session.startedAt),
+            session.endedAt === null ? "" : iso(session.endedAt),
+            session.state,
+            session.chain?.name ?? "",
+            session.chain === null ? "" : String(session.chain.id),
+            session.endpoint ?? "",
+            String(session.durationMs),
+            String(session.samples),
+            latency === null ? "" : String(latency.p50),
+            latency === null ? "" : String(latency.p95),
+            latency === null ? "" : String(latency.max),
+            blockTime === null ? "" : String(blockTime.medianSeconds),
+            blockTime === null ? "" : String(blockTime.minSeconds),
+            blockTime === null ? "" : String(blockTime.maxSeconds),
+            String(session.stalls),
+            String(session.gasSurges),
+            String(session.alerts),
+            String(session.errors),
+            session.chainDrift ? "true" : "false",
+            session.firstBlock === null ? "" : session.firstBlock.toString(),
+            session.lastBlock === null ? "" : session.lastBlock.toString(),
+            session.advancedBy.toString(),
+        ]
+            .map(csvCell)
+            .join(","));
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Write the CSV, creating parent directories; an existing file is replaced. */
+export function saveSessionsCsv(path, csv) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, csv);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SessionsArgError(`cannot write ${path}: ${reason}`);
+    }
+}
+export function toSessionsJson(report) {
+    return {
+        ok: report.sessions.every((session) => session.state !== "partial"),
+        log: report.path,
+        skippedLines: report.skippedLines,
+        sessions: report.sessions.map((session) => ({
+            id: session.id,
+            chain: session.chain,
+            endpoint: session.endpoint,
+            state: session.state,
+            startedAt: session.startedAt === null ? null : new Date(session.startedAt).toISOString(),
+            endedAt: session.endedAt === null ? null : new Date(session.endedAt).toISOString(),
+            durationMs: session.durationMs,
+            samples: session.samples,
+            latency: session.latency,
+            blockTime: session.blockTime,
+            stalls: session.stalls,
+            gasSurges: session.gasSurges,
+            alerts: session.alerts,
+            errors: session.errors,
+            chainDrift: session.chainDrift,
+            firstBlock: session.firstBlock === null ? null : session.firstBlock.toString(),
+            lastBlock: session.lastBlock === null ? null : session.lastBlock.toString(),
+            advancedBy: session.advancedBy.toString(),
+        })),
+        endpoints: report.endpoints.map((item) => ({
+            endpoint: item.endpoint,
+            sessions: item.sessions,
+            samples: item.samples,
+            latency: item.latency,
+            stalls: item.stalls,
+            gasSurges: item.gasSurges,
+            errors: item.errors,
+            stallRate: item.stallRate,
+        })),
+    };
+}

package/dist/signatures.d.ts

@@ -0,0 +1,13 @@
+import type { Abi } from "viem";
+export declare class SignaturesArgError extends Error {
+    constructor(message: string);
+}
+export interface SignaturesArgs {
+    /** ABI file to read, or null for the built-in ERC-20 ABI. */
+    abiPath: string | null;
+}
+export declare function parseSignaturesArgs(argv: string[]): SignaturesArgs;
+/** Every callable signature, sorted so overloads are easy to scan and copy. */
+export declare function callableSignatures(abi: Abi): string[];
+export declare function formatSignatures(signatures: string[], source: string): string;
+export declare function toSignaturesJson(signatures: string[], source: string): Record<string, unknown>;

package/dist/signatures.js

@@ -0,0 +1,43 @@
+import { signatureOf } from "./call.js";
+import { listViewFunctions } from "./views.js";
+export class SignaturesArgError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SignaturesArgError";
+    }
+}
+export function parseSignaturesArgs(argv) {
+    const positional = [];
+    for (const arg of argv) {
+        if (arg.startsWith("-"))
+            continue; // --json is handled by the caller.
+        positional.push(arg);
+    }
+    if (positional.length > 1) {
+        throw new SignaturesArgError(`Unexpected extra argument: ${positional[1]}.`);
+    }
+    return { abiPath: positional[0] ?? null };
+}
+/** Every callable signature, sorted so overloads are easy to scan and copy. */
+export function callableSignatures(abi) {
+    return listViewFunctions(abi).map(signatureOf).sort();
+}
+export function formatSignatures(signatures, source) {
+    const lines = [
+        "lwc — callable signatures",
+        "",
+        `  ${"abi".padEnd(14)}${source}`,
+        `  ${"signatures".padEnd(14)}${signatures.length} view/pure`,
+        "",
+    ];
+    if (signatures.length === 0) {
+        lines.push("  (no view or pure functions)");
+    }
+    else {
+        lines.push(...signatures.map((signature) => `  ${signature}`));
+    }
+    return lines.join("\n");
+}
+export function toSignaturesJson(signatures, source) {
+    return { ok: true, abi: source, count: signatures.length, signatures };
+}

package/dist/tokenfile.d.ts

@@ -0,0 +1,50 @@
+import { type Address } from "viem";
+export declare class TokenFileArgError extends Error {
+    constructor(message: string);
+}
+/** One entry as written to the file: a label when the input carried one. */
+export interface TokenFileEntry {
+    address: Address;
+    label: string | null;
+}
+export interface TokenFileArgs {
+    /** Unique addresses, checksummed, in the order given (or the merged order). */
+    addresses: Address[];
+    /** The same addresses with their labels, ready to write. */
+    entries: TokenFileEntry[];
+    /** Where to write the list, or "-" for stdout. */
+    outPath: string;
+    force: boolean;
+    /** Keep the entries already in the file and append only new addresses. */
+    merge: boolean;
+    /** Fixed sub-call budget for the verification reads, or null for the default. */
+    maxSubCalls: number | null;
+    /** Non-fatal label conflicts found while merging duplicate addresses. */
+    warnings: string[];
+}
+/**
+ * Keep the entries already in a list — same order, same labels — then append the
+ * addresses that are not there yet. A new label for an existing address replaces
+ * the old one, and a differing pair is reported in `warnings`.
+ */
+export declare function mergeTokenEntries(existing: readonly (Address | TokenFileEntry)[], added: readonly (Address | TokenFileEntry)[], warnings?: string[]): TokenFileEntry[];
+/**
+ * Build a `--tokens-file` list from command-line addresses. Pure local work: no
+ * RPC call is needed, and labels are carried through to the written file. With
+ * `--merge` the existing file is read so only new addresses are appended.
+ */
+export declare function parseTokenFileArgs(argv: string[]): TokenFileArgs;
+/**
+ * The written shape: a checksummed address string when there is no label, and an
+ * `{ address, label }` object when there is — both forms `--tokens-file` reads.
+ */
+export declare function tokenListItems(entries: readonly (Address | TokenFileEntry)[]): Array<Address | {
+    address: Address;
+    label: string;
+}>;
+/** JSON array in the format `--tokens-file` reads, labels included. */
+export declare function buildTokenListJson(entries: readonly (Address | TokenFileEntry)[]): string;
+/** Write the list (or return it for "-"), never replacing a file without force. */
+export declare function saveTokenList(outPath: string, entries: readonly (Address | TokenFileEntry)[], options?: {
+    force?: boolean;
+}): string;