lovewebconnection 0.0.0-stage → 0.2.0

package/dist/cache.d.ts

@@ -0,0 +1,37 @@
+import { type Address } from "viem";
+import type { ChainConfig } from "./chain.ts";
+import { MetadataCache } from "./metadata-cache.ts";
+export declare class CacheArgError extends Error {
+    constructor(message: string);
+}
+export interface CacheArgs {
+    /** Token addresses whose metadata entries should be removed. */
+    clear: Address[];
+}
+export interface CacheEntryReport {
+    address: Address;
+    symbol: string;
+    decimals: number;
+    /** Epoch milliseconds when the entry was verified; null for legacy entries. */
+    cachedAt: number | null;
+    /** Age in milliseconds; null when the entry has no timestamp. */
+    ageMs: number | null;
+}
+export interface CacheReport {
+    chainId: number;
+    chainName: string;
+    path: string;
+    entries: CacheEntryReport[];
+    removed: CacheEntryReport[];
+    warnings: string[];
+}
+/** `--clear` takes one or more token addresses, repeated or comma-separated. */
+export declare function parseCacheArgs(argv: string[]): CacheArgs;
+/**
+ * List the current chain's cached metadata and remove the requested entries.
+ * Removal is in-memory; the caller saves the cache so a failed write never
+ * hides the report.
+ */
+export declare function inspectMetadataCache(cache: MetadataCache, config: ChainConfig, path: string, args: CacheArgs, now?: number): CacheReport;
+export declare function formatMetadataCache(report: CacheReport): string;
+export declare function toCacheJson(report: CacheReport): Record<string, unknown>;

package/dist/cache.js

@@ -0,0 +1,128 @@
+import { getAddress, isAddress } from "viem";
+import { formatCacheAge, shortAddress } from "./balances.js";
+import { MetadataCache } from "./metadata-cache.js";
+export class CacheArgError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CacheArgError";
+    }
+}
+function addClearAddress(clear, raw) {
+    for (const part of raw.split(",")) {
+        const candidate = part.trim();
+        if (candidate.length === 0)
+            continue;
+        if (!isAddress(candidate)) {
+            throw new CacheArgError(`"${candidate}" is not a valid token address.`);
+        }
+        const address = getAddress(candidate);
+        if (!clear.includes(address))
+            clear.push(address);
+    }
+}
+/** `--clear` takes one or more token addresses, repeated or comma-separated. */
+export function parseCacheArgs(argv) {
+    const clear = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index] ?? "";
+        if (arg === "--clear") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new CacheArgError("--clear requires a token address.");
+            addClearAddress(clear, value);
+            index += 1;
+        }
+        else if (arg.startsWith("--clear=")) {
+            const value = arg.slice("--clear=".length);
+            if (!value)
+                throw new CacheArgError("--clear requires a token address.");
+            addClearAddress(clear, value);
+        }
+        else if (arg.startsWith("-")) {
+            // --json, --cache-file, and other global flags are handled by the CLI.
+            continue;
+        }
+        else {
+            throw new CacheArgError(`unexpected argument "${arg}"; the cache command takes no positional arguments.`);
+        }
+    }
+    return { clear };
+}
+function entryReport(entry, now) {
+    return {
+        address: entry.address,
+        symbol: entry.symbol,
+        decimals: entry.decimals,
+        cachedAt: entry.cachedAt,
+        ageMs: entry.cachedAt === null ? null : Math.max(0, now - entry.cachedAt),
+    };
+}
+/**
+ * List the current chain's cached metadata and remove the requested entries.
+ * Removal is in-memory; the caller saves the cache so a failed write never
+ * hides the report.
+ */
+export function inspectMetadataCache(cache, config, path, args, now = Date.now()) {
+    const warnings = [];
+    const removed = [];
+    const before = new Map(cache.list().map((entry) => [entry.address.toLowerCase(), entry]));
+    for (const address of args.clear) {
+        const entry = before.get(address.toLowerCase());
+        if (!entry || !cache.invalidate(address)) {
+            warnings.push(`token ${shortAddress(address)} is not in the ${config.name} metadata cache.`);
+            continue;
+        }
+        removed.push(entryReport(entry, now));
+    }
+    return {
+        chainId: config.chainId,
+        chainName: config.name,
+        path,
+        entries: cache.list().map((entry) => entryReport(entry, now)),
+        removed,
+        warnings,
+    };
+}
+export function formatMetadataCache(report) {
+    const lines = [
+        "lwc — cache",
+        "",
+        `  ${"file".padEnd(14)}${report.path}`,
+        `  ${"chain".padEnd(14)}${report.chainName} (${report.chainId})`,
+        `  ${"entries".padEnd(14)}${report.entries.length}`,
+    ];
+    if (report.removed.length > 0) {
+        lines.push(`  ${"removed".padEnd(14)}${report.removed.length}`);
+        for (const entry of report.removed) {
+            lines.push(`    ${shortAddress(entry.address)}  ${entry.symbol} (${entry.decimals} decimals)`);
+        }
+    }
+    if (report.entries.length === 0) {
+        lines.push("", "  no cached token metadata for this chain");
+    }
+    else {
+        lines.push("");
+        for (const entry of report.entries) {
+            const age = entry.ageMs === null ? "age unknown" : `cached ${formatCacheAge(entry.ageMs)}`;
+            lines.push(`  ${"token".padEnd(14)}${shortAddress(entry.address)}  ${entry.symbol} (${entry.decimals} decimals)  ${age}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function toCacheJson(report) {
+    const entryJson = (entry) => ({
+        address: entry.address,
+        symbol: entry.symbol,
+        decimals: entry.decimals,
+        cachedAt: entry.cachedAt,
+        ageMs: entry.ageMs,
+    });
+    return {
+        ok: true,
+        chain: { id: report.chainId, name: report.chainName },
+        cacheFile: report.path,
+        entries: report.entries.map(entryJson),
+        removed: report.removed.map(entryJson),
+        warnings: report.warnings,
+    };
+}

package/dist/call.d.ts

@@ -0,0 +1,46 @@
+import { type Abi, type AbiFunction, type Address, type PublicClient } from "viem";
+export declare class CallArgError extends Error {
+    constructor(message: string);
+}
+export interface CallArgs {
+    address: Address;
+    functionName: string;
+    /** null means no `--abi` was given, so the built-in ERC-20 ABI applies. */
+    abiPath: string | null;
+    args: unknown[];
+    block: "latest" | bigint;
+}
+export declare function parseCallArgs(argv: string[]): CallArgs;
+export declare function extractAbi(raw: unknown): Abi;
+export declare function loadAbi(path: string): Abi;
+export interface ResolvedAbi {
+    abi: Abi;
+    /** The path given to `--abi`, or the built-in label when none was given. */
+    source: string;
+}
+/** `--abi` is optional: without it the built-in ERC-20 ABI is used. */
+export declare function resolveAbi(abiPath: string | null): ResolvedAbi;
+export declare function signatureOf(fn: AbiFunction): string;
+/**
+ * Resolve a function by bare name or by full signature. A bare name works only
+ * when the ABI has one candidate: overloads are never guessed from the first
+ * entry, since that silently calls the wrong function when argument types line
+ * up. `balanceOf(address)` and `balanceOf( address )` are equivalent.
+ */
+export declare function findFunction(abi: Abi, nameOrSignature: string): AbiFunction;
+export declare function coerceArgs(fn: AbiFunction, rawArgs: unknown[]): unknown[];
+export interface CallOutcome {
+    blockNumber: bigint;
+    result: unknown;
+}
+export declare function callViewFunction(client: PublicClient, contract: Address, abi: Abi, fn: AbiFunction, args: unknown[], block: "latest" | bigint): Promise<CallOutcome>;
+export declare function formatValue(value: unknown): string;
+export interface CallDisplay {
+    contract: Address;
+    fn: AbiFunction;
+    blockNumber: bigint;
+    result: unknown;
+}
+export declare function formatCall(display: CallDisplay): string;
+export declare function serializeValue(value: unknown): unknown;
+export declare function toCallJson(display: CallDisplay): Record<string, unknown>;

package/dist/call.js

@@ -0,0 +1,377 @@
+import { existsSync, readFileSync } from "node:fs";
+import { getAddress, isAddress, isHex, } from "viem";
+import { DEFAULT_ABI_LABEL, DEFAULT_ERC20_ABI } from "./default-abi.js";
+export class CallArgError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CallArgError";
+    }
+}
+function parseBlock(raw) {
+    if (raw === "latest")
+        return "latest";
+    if (!/^\d+$/.test(raw)) {
+        throw new CallArgError(`--block must be "latest" or a block number, got "${raw}".`);
+    }
+    return BigInt(raw);
+}
+function parseArgsJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CallArgError(`--args is not valid JSON: ${raw}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new CallArgError(`--args must be a JSON array, e.g. --args '["0xabc…"]'.`);
+    }
+    return parsed;
+}
+export function parseCallArgs(argv) {
+    const positional = [];
+    const singleArgs = [];
+    let abiPath = null;
+    let argsJson = null;
+    let block = "latest";
+    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 CallArgError(`${flag} requires a value.`);
+            index += 1;
+            return value;
+        };
+        if (arg === "--abi") {
+            abiPath = readValue("--abi");
+        }
+        else if (arg === "--args") {
+            argsJson = readValue("--args");
+        }
+        else if (arg === "--arg") {
+            singleArgs.push(readValue("--arg"));
+        }
+        else if (arg === "--block") {
+            block = parseBlock(readValue("--block"));
+        }
+        else if (arg.startsWith("-")) {
+            // Other flags (e.g. --json) are handled by the caller.
+            continue;
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    const [addressRaw, functionName] = positional;
+    if (!addressRaw) {
+        throw new CallArgError("A contract address is required: lwc call <address> <function> [--abi <file>]");
+    }
+    if (!isAddress(addressRaw)) {
+        throw new CallArgError(`"${addressRaw}" is not a valid EVM address.`);
+    }
+    if (!functionName) {
+        throw new CallArgError("A function name or signature is required: lwc call <address> <function|signature> [--abi <file>]");
+    }
+    if (positional.length > 2) {
+        throw new CallArgError(`Unexpected extra argument: ${positional[2]}.`);
+    }
+    if (argsJson !== null && singleArgs.length > 0) {
+        throw new CallArgError("Use either --args or --arg, not both.");
+    }
+    let args = [];
+    if (argsJson !== null) {
+        args = parseArgsJson(argsJson);
+    }
+    else if (singleArgs.length > 0) {
+        args = singleArgs.map((raw) => {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                // Not JSON, so treat it as a literal string (e.g. 0xabc… or hello).
+                return raw;
+            }
+        });
+    }
+    return { address: getAddress(addressRaw), functionName, abiPath, args, block };
+}
+export function extractAbi(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    if (raw && typeof raw === "object" && Array.isArray(raw.abi)) {
+        return raw.abi;
+    }
+    throw new CallArgError('ABI file must be a JSON array of ABI items, or an object with an "abi" array.');
+}
+export function loadAbi(path) {
+    if (!existsSync(path)) {
+        throw new CallArgError(`ABI file not found: ${path}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new CallArgError(`ABI file is not valid JSON: ${path}`);
+    }
+    return extractAbi(raw);
+}
+/** `--abi` is optional: without it the built-in ERC-20 ABI is used. */
+export function resolveAbi(abiPath) {
+    if (abiPath === null)
+        return { abi: DEFAULT_ERC20_ABI, source: DEFAULT_ABI_LABEL };
+    return { abi: loadAbi(abiPath), source: abiPath };
+}
+/**
+ * Render an ABI parameter the way Solidity writes it: tuple components are
+ * expanded, and array suffixes are kept, so `f((uint256,address))` and
+ * `f((bool,bytes))` no longer both collapse to `f(tuple)`.
+ */
+function parameterType(param) {
+    const tuple = /^tuple(.*)$/.exec(param.type);
+    const components = param.components;
+    if (!tuple || components === undefined)
+        return param.type;
+    return `(${components.map(parameterType).join(",")})${tuple[1] ?? ""}`;
+}
+export function signatureOf(fn) {
+    return `${fn.name}(${(fn.inputs ?? []).map(parameterType).join(", ")})`;
+}
+function normalizeSignature(value) {
+    return value.replace(/\s+/g, "");
+}
+function availableFunctions(functions) {
+    const signatures = functions.map(signatureOf).sort();
+    return signatures.length > 0 ? signatures.join(", ") : "(none)";
+}
+/**
+ * Resolve a function by bare name or by full signature. A bare name works only
+ * when the ABI has one candidate: overloads are never guessed from the first
+ * entry, since that silently calls the wrong function when argument types line
+ * up. `balanceOf(address)` and `balanceOf( address )` are equivalent.
+ */
+export function findFunction(abi, nameOrSignature) {
+    const functions = abi.filter((item) => item.type === "function");
+    const selector = normalizeSignature(nameOrSignature);
+    let match;
+    if (selector.includes("(")) {
+        const exact = functions.find((fn) => normalizeSignature(signatureOf(fn)) === selector);
+        if (!exact) {
+            throw new CallArgError(`ABI has no function "${nameOrSignature}". Available: ${availableFunctions(functions)}.`);
+        }
+        match = exact;
+    }
+    else {
+        const overloads = functions.filter((fn) => fn.name === selector);
+        if (overloads.length === 0) {
+            throw new CallArgError(`ABI has no function "${nameOrSignature}". Available: ${availableFunctions(functions)}.`);
+        }
+        if (overloads.length > 1) {
+            throw new CallArgError(`"${nameOrSignature}" is overloaded; pass a full signature: ${overloads
+                .map(signatureOf)
+                .sort()
+                .join(", ")}.`);
+        }
+        match = overloads[0];
+    }
+    const mutability = match.stateMutability;
+    if (mutability !== "view" && mutability !== "pure") {
+        throw new CallArgError(`${signatureOf(match)} is ${mutability}; only view and pure functions can be called read-only.`);
+    }
+    return match;
+}
+/** JSON.stringify throws on a bigint, which would hide the coercion error. */
+function previewValue(value) {
+    if (typeof value === "bigint")
+        return `${value}n`;
+    try {
+        return previewValue(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function toBigInt(value, path, type) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isInteger(value)) {
+            throw new CallArgError(`${path} must be an integer for ${type}, got ${value}.`);
+        }
+        return BigInt(value);
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (/^-?\d+$/.test(trimmed))
+            return BigInt(trimmed);
+        if (/^0x[0-9a-fA-F]+$/.test(trimmed))
+            return BigInt(trimmed);
+    }
+    throw new CallArgError(`${path} must be an integer for ${type}, got ${previewValue(value)}.`);
+}
+function coerceValue(value, param, path) {
+    const type = param.type;
+    const arrayMatch = /^(.*)\[(\d*)\]$/.exec(type);
+    if (arrayMatch) {
+        const innerType = arrayMatch[1] ?? "";
+        const fixedLength = arrayMatch[2] ? Number(arrayMatch[2]) : null;
+        if (!Array.isArray(value)) {
+            throw new CallArgError(`${path} expects an array for type ${type}.`);
+        }
+        if (fixedLength !== null && value.length !== fixedLength) {
+            throw new CallArgError(`${path} expects ${fixedLength} items for type ${type}, got ${value.length}.`);
+        }
+        const innerParam = { ...param, type: innerType };
+        return value.map((item, index) => coerceValue(item, innerParam, `${path}[${index}]`));
+    }
+    if (type === "tuple") {
+        const components = param.components ?? [];
+        if (Array.isArray(value)) {
+            if (value.length !== components.length) {
+                throw new CallArgError(`${path} expects ${components.length} tuple fields, got ${value.length}.`);
+            }
+            return components.map((component, index) => coerceValue(value[index], component, `${path}.${component.name || index}`));
+        }
+        if (!value || typeof value !== "object") {
+            throw new CallArgError(`${path} expects an object or array for a tuple.`);
+        }
+        const record = value;
+        return Object.fromEntries(components.map((component, index) => {
+            const key = component.name && component.name.length > 0 ? component.name : String(index);
+            if (!(key in record)) {
+                throw new CallArgError(`${path} is missing tuple field "${key}".`);
+            }
+            return [key, coerceValue(record[key], component, `${path}.${key}`)];
+        }));
+    }
+    if (/^u?int\d*$/.test(type)) {
+        const amount = toBigInt(value, path, type);
+        if (type.startsWith("u") && amount < 0n) {
+            throw new CallArgError(`${path} must not be negative for type ${type}.`);
+        }
+        return amount;
+    }
+    if (type === "bool") {
+        if (typeof value === "boolean")
+            return value;
+        if (value === "true" || value === 1 || value === "1")
+            return true;
+        if (value === "false" || value === 0 || value === "0")
+            return false;
+        throw new CallArgError(`${path} expects true or false, got ${previewValue(value)}.`);
+    }
+    if (type === "address") {
+        if (typeof value !== "string" || !isAddress(value)) {
+            throw new CallArgError(`${path} expects an EVM address, got ${previewValue(value)}.`);
+        }
+        return getAddress(value);
+    }
+    if (type.startsWith("bytes")) {
+        const size = type === "bytes" ? null : Number(type.slice(5));
+        if (typeof value !== "string" || !isHex(value)) {
+            throw new CallArgError(`${path} expects a 0x-prefixed hex string for ${type}.`);
+        }
+        if (size !== null && value.length !== size * 2 + 2) {
+            throw new CallArgError(`${path} expects ${size} bytes for ${type}.`);
+        }
+        return value;
+    }
+    if (type === "string") {
+        if (typeof value === "string")
+            return value;
+        if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+            return String(value);
+        }
+        throw new CallArgError(`${path} expects a string, got ${previewValue(value)}.`);
+    }
+    return value;
+}
+export function coerceArgs(fn, rawArgs) {
+    const inputs = fn.inputs ?? [];
+    if (rawArgs.length !== inputs.length) {
+        throw new CallArgError(`${signatureOf(fn)} takes ${inputs.length} argument(s), got ${rawArgs.length}.`);
+    }
+    return inputs.map((input, index) => coerceValue(rawArgs[index], input, input.name && input.name.length > 0 ? input.name : `arg${index + 1}`));
+}
+export async function callViewFunction(client, contract, abi, fn, args, block) {
+    const result = await client.readContract({
+        address: contract,
+        abi,
+        functionName: fn.name,
+        args,
+        ...(block === "latest" ? {} : { blockNumber: block }),
+    });
+    return {
+        blockNumber: block === "latest" ? await client.getBlockNumber() : block,
+        result,
+    };
+}
+export function formatValue(value) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "boolean" || typeof value === "number")
+        return String(value);
+    if (value === null || value === undefined)
+        return "null";
+    if (Array.isArray(value))
+        return `[${value.map(formatValue).join(", ")}]`;
+    if (typeof value === "object") {
+        const entries = Object.entries(value).map(([key, item]) => `${key}: ${formatValue(item)}`);
+        return `{${entries.join(", ")}}`;
+    }
+    return String(value);
+}
+export function formatCall(display) {
+    const outputs = display.fn.outputs ?? [];
+    const values = Array.isArray(display.result) ? display.result : [display.result];
+    const lines = [
+        "lwc — contract call",
+        "",
+        `  ${"contract".padEnd(14)}${display.contract}`,
+        `  ${"function".padEnd(14)}${signatureOf(display.fn)}`,
+        `  ${"block".padEnd(14)}${display.blockNumber}`,
+        "",
+    ];
+    if (outputs.length <= 1) {
+        lines.push(`  ${"result".padEnd(14)}${formatValue(values[0])}`);
+    }
+    else {
+        outputs.forEach((output, index) => {
+            const label = output.name && output.name.length > 0 ? output.name : `[${index}]`;
+            lines.push(`  ${label.padEnd(14)}${formatValue(values[index])}`);
+        });
+    }
+    return lines.join("\n");
+}
+export function serializeValue(value) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (Array.isArray(value))
+        return value.map(serializeValue);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            serializeValue(item),
+        ]));
+    }
+    return value;
+}
+export function toCallJson(display) {
+    const outputs = display.fn.outputs ?? [];
+    const values = Array.isArray(display.result) ? display.result : [display.result];
+    return {
+        ok: true,
+        contract: display.contract,
+        function: { name: display.fn.name, signature: signatureOf(display.fn) },
+        blockNumber: display.blockNumber.toString(),
+        result: serializeValue(display.result),
+        outputs: outputs.map((output, index) => ({
+            name: output.name && output.name.length > 0 ? output.name : null,
+            type: output.type,
+            value: serializeValue(outputs.length === 1 ? display.result : values[index]),
+        })),
+    };
+}

package/dist/chain.d.ts

@@ -0,0 +1,97 @@
+import { type PublicClient } from "viem";
+export interface ChainConfig {
+    chainId: number;
+    name: string;
+    rpcUrl: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    /** Authorization header value for the RPC, or null when unauthenticated. */
+    authHeader: string | null;
+    timeoutMs: number;
+    /** Name of the built-in preset this config came from, or null for a custom chain. */
+    preset: string | null;
+    /**
+     * Endpoint to try when rpcUrl cannot answer. A preset supplies one, and
+     * LWC_FALLBACK_RPC_URL replaces it; null when there is none.
+     */
+    fallbackRpcUrl?: string | null;
+}
+export interface ChainPreset {
+    chainId: number;
+    name: string;
+    rpcUrl: string;
+    /** Second public endpoint from a different operator, used when rpcUrl is down. */
+    fallbackRpcUrl: string;
+    nativeSymbol: string;
+}
+/**
+ * Built-in chains. A preset supplies the chain id, endpoint, and native
+ * currency; LWC_RPC_URL, LWC_CHAIN_NAME, and LWC_NATIVE_SYMBOL still override
+ * individual values, so a preset is a starting point rather than a lock-in.
+ */
+export declare const CHAIN_PRESETS: Record<string, ChainPreset>;
+export declare function chainPresetNames(): string[];
+/** Find a preset by name (case-insensitive) or by its chain id. */
+export declare function resolveChainPreset(selector: string): ChainPreset | null;
+export interface ChainHealth {
+    chainId: number;
+    expectedChainId: number;
+    blockNumber: bigint;
+    blockTimestamp: bigint;
+    blockAgeSeconds: number;
+    gasPriceWei: bigint | null;
+    clientVersion: string | null;
+    latencyMs: number;
+    rpcHost: string;
+}
+export declare class ChainConfigError extends Error {
+    constructor(message: string);
+}
+export declare class ChainMismatchError extends Error {
+    readonly expected: number;
+    readonly actual: number;
+    readonly source: string;
+    constructor(expected: number, actual: number, source?: string);
+}
+/**
+ * Build the chain config from a preset name, a chain id, or explicit
+ * LWC_CHAIN_ID/LWC_RPC_URL values. An explicit selector (the --chain flag)
+ * wins over LWC_CHAIN.
+ */
+export declare function parseChainConfig(env: Record<string, string | undefined>, selector?: string | null): ChainConfig;
+/**
+ * A log-safe endpoint label: origin plus path, with query, fragment, and any
+ * key-like path segment removed. Provider attribution needs the host, not the
+ * credential that happens to sit in the URL.
+ */
+export declare function publicEndpoint(rpcUrl: string): string;
+/** Non-fatal advisories about the configured endpoint. */
+export declare function connectionWarnings(config: ChainConfig): string[];
+export declare function buildClient(config: ChainConfig): PublicClient;
+/**
+ * Read live state from the endpoint and verify it is the chain we expect.
+ * Throws ChainMismatchError when the RPC reports a different chainId.
+ */
+export declare function probe(client: PublicClient, config: ChainConfig): Promise<ChainHealth>;
+export interface ProbeOutcome {
+    health: ChainHealth;
+    /** The endpoint that answered: the backup when the primary was unhealthy. */
+    config: ChainConfig;
+    usedFallback: boolean;
+    /** Redacted primary endpoint, set only when the backup answered. */
+    primaryEndpoint: string | null;
+    /** Why the primary was skipped, set only when the backup answered. */
+    primaryError: string | null;
+}
+/**
+ * Probe the configured endpoint, falling back to the preset's second endpoint
+ * when the first cannot be used: unreachable, timing out, or answering with the
+ * wrong chain id. A configured auth header pins the probe to the primary, since
+ * sending someone's credentials to another operator would be a leak.
+ */
+export declare function probeWithFallback(clientFor: (config: ChainConfig) => PublicClient, config: ChainConfig): Promise<ProbeOutcome>;
+export declare function formatHealth(health: ChainHealth, config: ChainConfig, warnings?: string[]): string;
+export declare function toJsonPayload(health: ChainHealth, config: ChainConfig, warnings: string[], outcome?: Pick<ProbeOutcome, "usedFallback" | "primaryEndpoint" | "primaryError">): Record<string, unknown>;