lovewebconnection 0.0.0-stage → 0.2.1

package/dist/scan.js

@@ -0,0 +1,501 @@
+import { getAddress, isAddress } from "viem";
+import { parseCacheAge } from "./metadata-cache.js";
+import { countCacheStats, formatTokenAmount, loadAddressList, loadTokenList, MAX_SUB_CALLS, formatCacheAge, mergeTokenLabels, parseTokenSpec, prefetchMetadata, readBalances, rememberTokenLabel, shortAddress, TOKENS_PER_BATCH, } from "./balances.js";
+export class ScanArgError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ScanArgError";
+    }
+}
+/** How many owners are queried at once. */
+const SCAN_CONCURRENCY = 4;
+const MAX_BATCH_SIZE = 100;
+function parseBatchSize(raw) {
+    if (!/^\d+$/.test(raw)) {
+        throw new ScanArgError(`--batch-size must be a whole number, got "${raw}".`);
+    }
+    const value = Number(raw);
+    if (value < 1 || value > MAX_BATCH_SIZE) {
+        throw new ScanArgError(`--batch-size must be between 1 and ${MAX_BATCH_SIZE}.`);
+    }
+    return value;
+}
+function parseMaxCacheAge(raw) {
+    const parsed = parseCacheAge(raw);
+    if (!parsed.ok)
+        throw new ScanArgError(parsed.message);
+    return parsed.ms;
+}
+function parseStaleAfter(raw) {
+    const parsed = parseCacheAge(raw, "--stale-after");
+    if (!parsed.ok)
+        throw new ScanArgError(parsed.message);
+    return parsed.ms;
+}
+function parseMaxSubCalls(raw) {
+    if (!/^\d+$/.test(raw)) {
+        throw new ScanArgError(`--max-subcalls must be a whole number, got "${raw}".`);
+    }
+    const value = Number(raw);
+    if (value < 1 || value > MAX_SUB_CALLS) {
+        throw new ScanArgError(`--max-subcalls must be between 1 and ${MAX_SUB_CALLS}.`);
+    }
+    return value;
+}
+export function parseScanArgs(argv) {
+    const owners = [];
+    const rawTokens = [];
+    const tokenFiles = [];
+    const ownerFiles = [];
+    let csvPath = null;
+    let batchSize = TOKENS_PER_BATCH;
+    let maxSubCalls = null;
+    let sawBatchSize = false;
+    let failOnRetry = false;
+    let quiet = false;
+    let maxCacheAgeMs = null;
+    let staleAfterMs = null;
+    const addOwner = (raw) => {
+        const candidate = raw.trim();
+        if (!candidate)
+            return;
+        if (!isAddress(candidate)) {
+            throw new ScanArgError(`"${candidate}" is not a valid owner address.`);
+        }
+        owners.push(getAddress(candidate));
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index] ?? "";
+        if (arg === "--owner") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new ScanArgError("--owner requires an address.");
+            addOwner(value);
+            index += 1;
+        }
+        else if (arg.startsWith("--owner=")) {
+            addOwner(arg.slice("--owner=".length));
+        }
+        else if (arg === "--owners-file") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new ScanArgError("--owners-file requires a path.");
+            ownerFiles.push(value);
+            index += 1;
+        }
+        else if (arg.startsWith("--owners-file=")) {
+            const value = arg.slice("--owners-file=".length);
+            if (!value)
+                throw new ScanArgError("--owners-file requires a path.");
+            ownerFiles.push(value);
+        }
+        else if (arg === "--token") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new ScanArgError("--token requires an address.");
+            rawTokens.push(value);
+            index += 1;
+        }
+        else if (arg.startsWith("--token=")) {
+            rawTokens.push(arg.slice("--token=".length));
+        }
+        else if (arg === "--tokens") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new ScanArgError("--tokens requires a comma-separated list.");
+            rawTokens.push(...value.split(","));
+            index += 1;
+        }
+        else if (arg.startsWith("--tokens=")) {
+            rawTokens.push(...arg.slice("--tokens=".length).split(","));
+        }
+        else if (arg === "--tokens-file") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new ScanArgError("--tokens-file requires a path.");
+            tokenFiles.push(value);
+            index += 1;
+        }
+        else if (arg.startsWith("--tokens-file=")) {
+            const value = arg.slice("--tokens-file=".length);
+            if (!value)
+                throw new ScanArgError("--tokens-file requires a path.");
+            tokenFiles.push(value);
+        }
+        else if (arg === "--batch-size") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new ScanArgError("--batch-size requires a value.");
+            batchSize = parseBatchSize(value);
+            sawBatchSize = true;
+            index += 1;
+        }
+        else if (arg.startsWith("--batch-size=")) {
+            batchSize = parseBatchSize(arg.slice("--batch-size=".length));
+            sawBatchSize = true;
+        }
+        else if (arg === "--max-subcalls") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new ScanArgError("--max-subcalls requires a value.");
+            maxSubCalls = parseMaxSubCalls(value);
+            index += 1;
+        }
+        else if (arg.startsWith("--max-subcalls=")) {
+            maxSubCalls = parseMaxSubCalls(arg.slice("--max-subcalls=".length));
+        }
+        else if (arg === "--fail-on-retry") {
+            failOnRetry = true;
+        }
+        else if (arg === "--quiet") {
+            quiet = true;
+        }
+        else if (arg === "--max-cache-age") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new ScanArgError("--max-cache-age requires a duration.");
+            maxCacheAgeMs = parseMaxCacheAge(value);
+            index += 1;
+        }
+        else if (arg.startsWith("--max-cache-age=")) {
+            maxCacheAgeMs = parseMaxCacheAge(arg.slice("--max-cache-age=".length));
+        }
+        else if (arg === "--stale-after") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new ScanArgError("--stale-after requires a duration.");
+            staleAfterMs = parseStaleAfter(value);
+            index += 1;
+        }
+        else if (arg.startsWith("--stale-after=")) {
+            staleAfterMs = parseStaleAfter(arg.slice("--stale-after=".length));
+        }
+        else if (arg === "--csv") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new ScanArgError("--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 ScanArgError("--csv requires a path, or - for stdout.");
+            csvPath = value;
+        }
+        else if (arg.startsWith("-")) {
+            // Other flags (e.g. --json) are handled by the caller.
+            continue;
+        }
+        else {
+            addOwner(arg);
+        }
+    }
+    const tokens = [];
+    const warnings = [];
+    const inlineLabels = new Map();
+    const fileLabels = new Map();
+    const loadList = (fn) => {
+        try {
+            return fn();
+        }
+        catch (error) {
+            throw new ScanArgError(error instanceof Error ? error.message : String(error));
+        }
+    };
+    for (const raw of rawTokens) {
+        const candidate = raw.trim();
+        if (!candidate)
+            continue;
+        const entry = loadList(() => parseTokenSpec(candidate));
+        tokens.push(entry.address);
+        rememberTokenLabel(entry, inlineLabels, warnings);
+    }
+    for (const file of tokenFiles) {
+        for (const entry of loadList(() => loadTokenList(file))) {
+            tokens.push(entry.address);
+            rememberTokenLabel(entry, fileLabels, warnings);
+        }
+    }
+    const labels = mergeTokenLabels(inlineLabels, fileLabels, warnings);
+    for (const file of ownerFiles) {
+        owners.push(...loadList(() => loadAddressList(file, "owner list", ["owners", "addresses"])));
+    }
+    const uniqueOwners = [...new Set(owners)];
+    if (uniqueOwners.length === 0) {
+        throw new ScanArgError("at least one owner is required: lwc scan 0xaddress… --tokens-file ./tokens.json --csv out.csv");
+    }
+    if (sawBatchSize && maxSubCalls !== null) {
+        throw new ScanArgError("use either --batch-size or --max-subcalls, not both.");
+    }
+    return {
+        owners: uniqueOwners,
+        tokens: [...new Set(tokens)],
+        labels,
+        csvPath,
+        batchSize,
+        maxSubCalls,
+        failOnRetry,
+        quiet,
+        maxCacheAgeMs,
+        staleAfterMs,
+        warnings,
+    };
+}
+async function mapLimit(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length) {
+            const index = next;
+            next += 1;
+            results[index] = await fn(items[index]);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+/** Prefer the first owner that resolved a token's metadata for the column header. */
+function mergeTokens(perOwner) {
+    const first = perOwner[0] ?? [];
+    return first.map((token, index) => {
+        for (const list of perOwner) {
+            const candidate = list[index];
+            if (candidate && candidate.decimals !== null)
+                return candidate;
+        }
+        return token;
+    });
+}
+export async function scanBalances(client, config, owners, tokens, options = {}) {
+    if (options.cache && options.refreshCache) {
+        for (const token of tokens)
+            options.cache.invalidate(token);
+    }
+    if (options.cache && options.maxCacheAgeMs !== undefined) {
+        options.cache.invalidateStale(options.maxCacheAgeMs);
+    }
+    const cacheStats = countCacheStats(tokens, options.cache);
+    if (options.cache) {
+        await prefetchMetadata(client, tokens, options.cache, options.batchSize, options.maxSubCalls);
+    }
+    // A scan refreshes metadata once above; owners must reuse the fresh entries.
+    const ownerOptions = { ...options, refreshCache: false };
+    const reports = await mapLimit(owners, SCAN_CONCURRENCY, (owner) => readBalances(client, config, owner, tokens, ownerOptions));
+    const warnings = reports
+        .filter((report) => report.batchWarning !== null)
+        .map((report) => `${shortAddress(report.owner)}: ${report.batchWarning}`);
+    const chunks = reports.flatMap((report) => report.chunks.map((chunk) => ({
+        owner: report.owner,
+        index: chunk.index,
+        total: chunk.total,
+        tokens: chunk.tokens,
+        status: chunk.status,
+        error: chunk.error,
+        individual: chunk.individual,
+    })));
+    const fallbacks = [];
+    for (const report of reports) {
+        const tokenByAddress = new Map(report.tokens.map((token) => [token.address.toLowerCase(), token]));
+        for (const chunk of report.chunks) {
+            for (const address of chunk.individual) {
+                const token = tokenByAddress.get(address.toLowerCase());
+                fallbacks.push({
+                    owner: report.owner,
+                    token: address,
+                    symbol: token?.symbol ?? shortAddress(address),
+                    label: token?.label ?? null,
+                    chunk: chunk.index,
+                    chunks: chunk.total,
+                    error: chunk.error,
+                });
+            }
+        }
+    }
+    const recovery = reports.reduce((sum, report) => ({
+        failedChunks: sum.failedChunks + report.recovery.failedChunks,
+        retryRequests: sum.retryRequests + report.recovery.retryRequests,
+        recoveredChunks: sum.recoveredChunks + report.recovery.recoveredChunks,
+    }), { failedChunks: 0, retryRequests: 0, recoveredChunks: 0 });
+    return {
+        chainId: config.chainId,
+        chainName: config.name,
+        blockNumber: reports[0]?.blockNumber ?? 0n,
+        nativeSymbol: config.nativeCurrency.symbol,
+        nativeDecimals: config.nativeCurrency.decimals,
+        owners,
+        tokens: mergeTokens(reports.map((report) => report.tokens)),
+        rows: reports.map((report) => ({
+            owner: report.owner,
+            native: report.native.balance,
+            balances: report.tokens.map((token) => token.balance),
+        })),
+        warnings,
+        batchSize: reports[0]?.batchSize ?? options.batchSize ?? TOKENS_PER_BATCH,
+        chunkCount: chunks.length,
+        chunks,
+        fallbacks,
+        recovery,
+        cache: cacheStats,
+    };
+}
+function columnHeading(token) {
+    if (token.decimals === null)
+        return shortAddress(token.address);
+    return `${token.symbol} (${shortAddress(token.address)})`;
+}
+function columnLabel(token) {
+    const tag = token.label ? ` [${token.label}]` : "";
+    if (token.decimals === null)
+        return `${shortAddress(token.address)}${tag}`;
+    return `${token.symbol}${tag} (${shortAddress(token.address)})`;
+}
+function labelCell(tokens) {
+    return tokens
+        .filter((token) => token.label !== null)
+        .map((token) => `${columnHeading(token)}: ${token.label}`)
+        .join(" | ");
+}
+function flagCell(tokens) {
+    return tokens
+        .filter((token) => token.issue !== null)
+        .map((token) => `${columnLabel(token)}: ${token.issue}`)
+        .join(" | ");
+}
+export function csvCell(value) {
+    return /[",\n\r]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+}
+export function scanCsv(report) {
+    const header = [
+        "owner",
+        `native (${report.nativeSymbol})`,
+        ...report.tokens.map(columnHeading),
+        "labels",
+        "flag",
+    ];
+    const labels = labelCell(report.tokens);
+    const flags = flagCell(report.tokens);
+    const lines = [header.map(csvCell).join(",")];
+    for (const row of report.rows) {
+        const cells = [
+            row.owner,
+            formatTokenAmount(row.native, report.nativeDecimals),
+        ];
+        report.tokens.forEach((token, index) => {
+            const balance = row.balances[index] ?? null;
+            cells.push(balance === null || token.decimals === null
+                ? ""
+                : formatTokenAmount(balance, token.decimals));
+        });
+        cells.push(labels, flags);
+        lines.push(cells.map(csvCell).join(","));
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function formatScan(report) {
+    const lines = [
+        "lwc — scan",
+        "",
+        `  chain         ${report.chainName} (${report.chainId})`,
+        `  block         ${report.blockNumber}`,
+        `  owners        ${report.owners.length}`,
+        `  tokens        ${report.tokens.length}`,
+    ];
+    if (report.chunks.length > 0) {
+        const count = (status) => report.chunks.filter((chunk) => chunk.status === status).length;
+        const recovered = count("recovered");
+        const partial = count("partial");
+        const failed = count("failed");
+        if (recovered + partial + failed > 0) {
+            lines.push(`  chunks        ${report.chunks.length} (${recovered} recovered, ${partial} partial, ${failed} failed)`);
+        }
+    }
+    if (report.recovery.failedChunks > 0) {
+        const failed = report.recovery.failedChunks;
+        const retries = report.recovery.retryRequests;
+        const recovered = report.recovery.recoveredChunks;
+        lines.push(`  recovery      ${failed} failed chunk${failed === 1 ? "" : "s"}, ${retries} retry request${retries === 1 ? "" : "s"}, ${recovered} recovered`);
+    }
+    for (const row of report.rows) {
+        lines.push("");
+        lines.push(`  owner         ${row.owner}`);
+        lines.push(`    native      ${formatTokenAmount(row.native, report.nativeDecimals)} ${report.nativeSymbol}`);
+        report.tokens.forEach((token, index) => {
+            const balance = row.balances[index] ?? null;
+            const value = balance === null || token.decimals === null
+                ? "unreadable"
+                : formatTokenAmount(balance, token.decimals);
+            const cached = token.cacheAgeMs == null ? "" : ` [cached ${formatCacheAge(token.cacheAgeMs)}]`;
+            lines.push(`    ${columnLabel(token)}  ${value}${cached}`);
+        });
+    }
+    for (const warning of report.warnings) {
+        lines.push("");
+        lines.push(`  warning       ${warning}`);
+    }
+    if (report.fallbacks.length > 0) {
+        const count = report.fallbacks.length;
+        lines.push("");
+        lines.push(`  fallbacks     ${count} token${count === 1 ? "" : "s"} read individually`);
+        for (const fallback of report.fallbacks) {
+            const tag = fallback.label ? ` [${fallback.label}]` : "";
+            lines.push(`    ${shortAddress(fallback.owner)}  chunk ${fallback.chunk}/${fallback.chunks}  ${fallback.token} ${fallback.symbol}${tag}`);
+        }
+    }
+    for (const token of report.tokens) {
+        if (token.issue) {
+            lines.push("");
+            lines.push(`  flag          token ${shortAddress(token.address)}: ${token.issue}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function toScanJson(report) {
+    return {
+        ok: true,
+        chain: { id: report.chainId, name: report.chainName },
+        blockNumber: report.blockNumber.toString(),
+        batchSize: report.batchSize,
+        chunkCount: report.chunkCount,
+        cache: { hits: report.cache.hits, misses: report.cache.misses },
+        recovery: {
+            failedChunks: report.recovery.failedChunks,
+            retryRequests: report.recovery.retryRequests,
+            recoveredChunks: report.recovery.recoveredChunks,
+        },
+        native: { symbol: report.nativeSymbol, decimals: report.nativeDecimals },
+        owners: report.owners,
+        tokens: report.tokens.map((token) => ({
+            address: token.address,
+            symbol: token.symbol,
+            label: token.label,
+            decimals: token.decimals,
+            issue: token.issue,
+            cacheAgeMs: token.cacheAgeMs,
+        })),
+        rows: report.rows.map((row) => ({
+            owner: row.owner,
+            native: row.native.toString(),
+            balances: row.balances.map((balance) => (balance === null ? null : balance.toString())),
+        })),
+        warnings: report.warnings,
+        chunks: report.chunks.map((chunk) => ({
+            owner: chunk.owner,
+            chunk: chunk.index,
+            total: chunk.total,
+            tokens: chunk.tokens,
+            status: chunk.status,
+            error: chunk.error,
+            individual: chunk.individual,
+        })),
+        fallbacks: report.fallbacks.map((fallback) => ({
+            owner: fallback.owner,
+            token: fallback.token,
+            symbol: fallback.symbol,
+            label: fallback.label,
+            chunk: fallback.chunk,
+            chunks: fallback.chunks,
+            error: fallback.error,
+        })),
+    };
+}

package/dist/sessions.d.ts

@@ -0,0 +1,104 @@
+export declare class SessionsArgError extends Error {
+    constructor(message: string);
+}
+export interface SessionsArgs {
+    path: string;
+    /** Only sessions that started at or after this epoch-ms time; null for no limit. */
+    since: number | null;
+    /** Only sessions whose id starts with one of these prefixes; empty for all. */
+    sessionPrefixes: string[];
+    /** Where to write the per-session CSV, "-" for stdout, or null for the table. */
+    csvPath: string | null;
+}
+export declare function parseSessionsArgs(argv: string[]): SessionsArgs;
+export declare function readWatchLog(path: string): string;
+export interface SessionLatencyStats {
+    count: number;
+    p50: number;
+    p95: number;
+    max: number;
+}
+export interface SessionBlockTimeStats {
+    count: number;
+    medianSeconds: number;
+    minSeconds: number;
+    maxSeconds: number;
+}
+export type SessionState = "complete" | "aborted" | "partial";
+export interface SessionSummary {
+    id: string;
+    chain: {
+        id: number;
+        name: string;
+    } | null;
+    /** Sanitised RPC endpoint from the `start` line; null in older logs. */
+    endpoint: string | null;
+    state: SessionState;
+    /** Epoch milliseconds of the `start` line; null when the log is missing it. */
+    startedAt: number | null;
+    endedAt: number | null;
+    durationMs: number;
+    samples: number;
+    latency: SessionLatencyStats;
+    blockTime: SessionBlockTimeStats;
+    stalls: number;
+    gasSurges: number;
+    alerts: number;
+    errors: number;
+    chainDrift: boolean;
+    firstBlock: bigint | null;
+    lastBlock: bigint | null;
+    advancedBy: bigint;
+}
+export interface EndpointSummary {
+    /** RPC host from the session's `start` line; null in older logs. */
+    endpoint: string | null;
+    sessions: number;
+    samples: number;
+    /** Percentiles pooled from every poll, so busy sessions weigh more. */
+    latency: SessionLatencyStats;
+    stalls: number;
+    gasSurges: number;
+    errors: number;
+    /** Stalls per poll across these sessions; 0 when there were no polls. */
+    stallRate: number;
+}
+export interface SessionsReport {
+    path: string;
+    sessions: SessionSummary[];
+    /** Sessions pooled by the RPC host that served them. */
+    endpoints: EndpointSummary[];
+    /** Lines that were not valid JSON objects, or had no session id. */
+    skippedLines: number;
+}
+export interface SessionsFilter {
+    /** Drop sessions that started before this epoch-ms time. */
+    since?: number | null;
+    /** Keep only sessions whose id starts with one of these prefixes. */
+    sessionPrefixes?: string[];
+}
+/**
+ * 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 declare function summarizeWatchLog(text: string, filter?: SessionsFilter): {
+    sessions: SessionSummary[];
+    endpoints: EndpointSummary[];
+    skippedLines: number;
+};
+export declare function formatSessions(report: SessionsReport): string;
+export declare const SESSIONS_CSV_HEADER: readonly ["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 declare function sessionsCsv(report: Pick<SessionsReport, "sessions">): string;
+/** Write the CSV, creating parent directories; an existing file is replaced. */
+export declare function saveSessionsCsv(path: string, csv: string): void;
+export declare function toSessionsJson(report: SessionsReport): Record<string, unknown>;