@jinn-network/client 0.1.7 → 0.1.8-canary.09a3b2f6

package/dist/preflight/pidfile-liveness.js

@@ -0,0 +1,117 @@
+/**
+ * Pidfile liveness preflight (issue #649). Classifies the recorded PID and
+ * returns a discriminated decision; side-effect-free so the caller owns the
+ * unlink (mirrors the idiom at `client/src/mcp/operator-server.ts:209-213`).
+ *
+ * Branches (load-bearing — see #649 acceptance criteria):
+ *   - File missing               → { decision: 'proceed' }
+ *   - File malformed (NaN/empty) → { decision: 'unlink-stale', reason: 'malformed' }
+ *   - PID 1 or our own pid       → { decision: 'unlink-stale', reason: 'self-or-pid1-container' }
+ *   - process.kill(pid, 0) ESRCH → { decision: 'unlink-stale', reason: 'esrch' }
+ *   - process.kill(pid, 0) ok    → { decision: 'refuse', reason: 'alive' }
+ *   - process.kill(pid, 0) EPERM → { decision: 'refuse', reason: 'eperm' }
+ *   - any other errno            → { decision: 'refuse', reason: 'unknown' }
+ *
+ * The PID-1/self branch classifies *before* the `process.kill` probe (#805): in
+ * a container the daemon is PID 1, whose pidfile outlives the container on the
+ * persistent volume; `process.kill(1, 0)` always succeeds, so a probe-first
+ * order would mis-classify the stale record as a live sibling and crash-loop.
+ *
+ * `.trim()` before `parseInt` is required: `main.ts` writes the PID with a
+ * trailing `\n` (see `client/src/main.ts` writeFileSync near the pidfile site).
+ */
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { emitEnvelope } from '../errors/envelope.js';
+import { emitStructured } from '../events/emitter.js';
+export function checkPidfileLiveness(input) {
+    const { pidPath } = input;
+    if (!existsSync(pidPath)) {
+        return { decision: 'proceed' };
+    }
+    let raw;
+    try {
+        raw = readFileSync(pidPath, 'utf-8');
+    }
+    catch {
+        // Unreadable pidfile: treat as stale. If the caller's subsequent write also
+        // fails, that surfaces via main.ts's `writeFileSync`.
+        return { decision: 'unlink-stale', pid: null, pidfilePath: pidPath, reason: 'malformed' };
+    }
+    const parsed = parseInt(raw.trim(), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return { decision: 'unlink-stale', pid: null, pidfilePath: pidPath, reason: 'malformed' };
+    }
+    // #805: in a container the daemon is PID 1; the pidfile on the persistent
+    // volume outlives the container, and `process.kill(1, 0)` always succeeds, so
+    // we must classify the self/PID-1 record as stale *before* the liveness probe
+    // below — otherwise the probe reports it alive and the daemon crash-loops. A
+    // record of our own pid is likewise self, never a live sibling.
+    if (parsed === 1 || parsed === process.pid) {
+        return { decision: 'unlink-stale', pid: parsed, pidfilePath: pidPath, reason: 'self-or-pid1-container' };
+    }
+    try {
+        process.kill(parsed, 0);
+        return { decision: 'refuse', pid: parsed, pidfilePath: pidPath, reason: 'alive' };
+    }
+    catch (err) {
+        const errno = err.code;
+        if (errno === 'ESRCH') {
+            return { decision: 'unlink-stale', pid: parsed, pidfilePath: pidPath, reason: 'esrch' };
+        }
+        if (errno === 'EPERM') {
+            return { decision: 'refuse', pid: parsed, pidfilePath: pidPath, reason: 'eperm' };
+        }
+        // Any other errno: conservative refuse rather than risk trampling a daemon
+        // we can't classify.
+        return { decision: 'refuse', pid: parsed, pidfilePath: pidPath, reason: 'unknown' };
+    }
+}
+/**
+ * Apply the pidfile-liveness gate at `jinn run` startup (#649). On `refuse`
+ * emits the `invalid_invocation` envelope and exits (does not return); on
+ * `unlink-stale` logs the cleanup, removes the stale pidfile, and returns;
+ * on `proceed` returns immediately. Callers MUST write the pidfile themselves
+ * after this returns — the helper deliberately stops short of the write so the
+ * "// DO NOT add store mutations above this line — see #649" invariant in
+ * main.ts stays visible at the call site.
+ */
+export function applyPidfileLivenessGate(pidPath, sinks = {}) {
+    const liveness = checkPidfileLiveness({ pidPath });
+    if (liveness.decision === 'refuse') {
+        emitEnvelope({
+            code: 'invalid_invocation',
+            message: `Another jinn daemon is already running (PID ${liveness.pid}).`,
+            hint: 'Run `jinn stop` to terminate it, or set JINN_EARNING_DIR to a different earning directory.',
+            exampleCli: 'jinn stop',
+            details: {
+                field: 'daemon_pidfile',
+                pid: liveness.pid,
+                pidfilePath: pidPath,
+                reason: liveness.reason,
+            },
+        }, sinks);
+        // emitEnvelope calls process.exit in production; the test sink may throw
+        // or no-op. Either way control does not fall through to the writeFileSync
+        // in the caller.
+        return;
+    }
+    if (liveness.decision === 'unlink-stale') {
+        emitStructured({
+            kind: 'system',
+            message: `cleaning up stale pidfile (${liveness.reason})`,
+            details: {
+                phase: 'preflight',
+                pidfilePath: pidPath,
+                reason: liveness.reason,
+                pid: liveness.pid,
+            },
+        });
+        try {
+            unlinkSync(pidPath);
+        }
+        catch {
+            /* best-effort — the writeFileSync that follows surfaces any real problem */
+        }
+    }
+}
+//# sourceMappingURL=pidfile-liveness.js.map

package/dist/preflight/pidfile-liveness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pidfile-liveness.js","sourceRoot":"","sources":["../../src/preflight/pidfile-liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,EAAE,YAAY,EAAsB,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAqBtD,MAAM,UAAU,oBAAoB,CAClC,KAAgC;IAEhC,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC1B,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;IACjC,CAAC;IAED,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;QAC5E,sDAAsD;QACtD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC5F,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC5C,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC5F,CAAC;IAED,0EAA0E;IAC1E,8EAA8E;IAC9E,8EAA8E;IAC9E,6EAA6E;IAC7E,gEAAgE;IAChE,IAAI,MAAM,KAAK,CAAC,IAAI,MAAM,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC;QAC3C,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IAC3G,CAAC;IAED,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACxB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACpF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,KAAK,GAAI,GAA6B,CAAC,IAAI,CAAC;QAClD,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;YACtB,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAC1F,CAAC;QACD,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;YACtB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QACpF,CAAC;QACD,2EAA2E;QAC3E,qBAAqB;QACrB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACtF,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAe,EACf,QAAuB,EAAE;IAEzB,MAAM,QAAQ,GAAG,oBAAoB,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IACnD,IAAI,QAAQ,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACnC,YAAY,CACV;YACE,IAAI,EAAE,oBAAoB;YAC1B,OAAO,EAAE,+CAA+C,QAAQ,CAAC,GAAG,IAAI;YACxE,IAAI,EAAE,4FAA4F;YAClG,UAAU,EAAE,WAAW;YACvB,OAAO,EAAE;gBACP,KAAK,EAAE,gBAAgB;gBACvB,GAAG,EAAE,QAAQ,CAAC,GAAG;gBACjB,WAAW,EAAE,OAAO;gBACpB,MAAM,EAAE,QAAQ,CAAC,MAAM;aACxB;SACF,EACD,KAAK,CACN,CAAC;QACF,yEAAyE;QACzE,0EAA0E;QAC1E,iBAAiB;QACjB,OAAO;IACT,CAAC;IACD,IAAI,QAAQ,CAAC,QAAQ,KAAK,cAAc,EAAE,CAAC;QACzC,cAAc,CAAC;YACb,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,8BAA8B,QAAQ,CAAC,MAAM,GAAG;YACzD,OAAO,EAAE;gBACP,KAAK,EAAE,WAAW;gBAClB,WAAW,EAAE,OAAO;gBACpB,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,GAAG,EAAE,QAAQ,CAAC,GAAG;aAClB;SACF,CAAC,CAAC;QACH,IAAI,CAAC;YACH,UAAU,CAAC,OAAO,CAAC,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,4EAA4E;QAC9E,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/preflight/rpc-network.d.ts

@@ -42,3 +42,43 @@ export declare function logRpcLocalDevToStderr(r: RpcNetworkPreflightOk, write?:
 export declare function rpcHostForDisplay(rpcUrl: string): string;
 export declare function checkRpcNetwork(config: Pick<JinnConfig, 'network' | 'rpcUrl'>): Promise<RpcNetworkPreflightResult>;
 export declare function rpcNetworkFailureHint(result: RpcNetworkPreflightFail): string;
+/** Layer label for log lines and AC7 summary formatting. */
+export type ProbeLayer = 'L1' | 'L2';
+export type ProbeOk = {
+    ok: true;
+    host: string;
+    latencyMs: number;
+};
+export type ProbeFail = {
+    ok: false;
+    host: string;
+    /** HTTP status when applicable (4xx / 5xx). */
+    code?: number;
+    /** Failure shape when no HTTP status is available. */
+    reason?: 'unreachable' | 'unknown';
+    message: string;
+};
+export type ProbeResult = ProbeOk | ProbeFail;
+export interface ProbeFallbackChainOptions {
+    /** Logger for per-slot lines. Defaults to `console.error`. */
+    log?: (message: string) => void;
+}
+/**
+ * Probe each URL in a fallback chain with a per-slot `eth_blockNumber` call.
+ * Records ok/latency or a structured failure (HTTP status / unreachable).
+ *
+ * The probe is **log-only** — it never throws on per-slot failures. Startup
+ * gating remains the job of {@link checkRpcNetwork}, which fails loud on
+ * chain-id mismatch.
+ *
+ * Per AC9 (issue #592): emits one log line per slot
+ *   `[rpc] <layer> <host> ok latency=Nms`
+ *   `[rpc] <layer> <host> warn <http-status>`     (e.g. 429, 503)
+ *   `[rpc] <layer> <host> warn unreachable: <message>`
+ */
+export declare function probeFallbackChain(urls: readonly string[], network: ExpectedRpcNetwork, layer: ProbeLayer, options?: ProbeFallbackChainOptions): Promise<ProbeResult[]>;
+/**
+ * Boot-log summary line for a fallback chain, formatted per AC7:
+ *   `[rpc] L2 transport: fallback chain (N providers) — primary=<host>`
+ */
+export declare function summarizeFallbackChain(layer: ProbeLayer, urls: readonly string[]): string;

package/dist/preflight/rpc-network.js

@@ -1,5 +1,6 @@
-import { createPublicClient, http } from 'viem';
+import { createPublicClient, http, HttpRequestError } from 'viem';
 import { base, baseSepolia } from 'viem/chains';
+import { describeFallbackChain, maskRpcHost } from '../rpc/transport.js';
 export function expectedChainIdForNetwork(network) {
     return network === 'testnet' ? 84532 : 8453;
 }
@@ -118,4 +119,69 @@ export function rpcNetworkFailureHint(result) {
     }
     return 'Set rpcUrl to a Base mainnet endpoint such as https://mainnet.base.org, or set BASE_RPC_URL.';
 }
+function classifyProbeError(host, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof HttpRequestError && typeof err.status === 'number') {
+        return { ok: false, host, code: err.status, message };
+    }
+    // viem wraps HTTP errors inside other shapes; walk the cause chain.
+    let cur = err?.cause;
+    while (cur) {
+        if (cur instanceof HttpRequestError && typeof cur.status === 'number') {
+            return { ok: false, host, code: cur.status, message };
+        }
+        cur = cur.cause;
+    }
+    return { ok: false, host, reason: 'unreachable', message };
+}
+/**
+ * Probe each URL in a fallback chain with a per-slot `eth_blockNumber` call.
+ * Records ok/latency or a structured failure (HTTP status / unreachable).
+ *
+ * The probe is **log-only** — it never throws on per-slot failures. Startup
+ * gating remains the job of {@link checkRpcNetwork}, which fails loud on
+ * chain-id mismatch.
+ *
+ * Per AC9 (issue #592): emits one log line per slot
+ *   `[rpc] <layer> <host> ok latency=Nms`
+ *   `[rpc] <layer> <host> warn <http-status>`     (e.g. 429, 503)
+ *   `[rpc] <layer> <host> warn unreachable: <message>`
+ */
+export async function probeFallbackChain(urls, network, layer, options = {}) {
+    const log = options.log ?? ((m) => process.stderr.write(`${m}\n`));
+    // Chain is informational only — eth_blockNumber doesn't depend on chain
+    // identity. Both L1 and L2 layers reuse the same Base/Base-Sepolia pair
+    // since this is just used to satisfy viem's typing.
+    const chain = network === 'testnet' ? baseSepolia : base;
+    const results = [];
+    for (const url of urls) {
+        const host = maskRpcHost(url);
+        const client = createPublicClient({ chain, transport: http(url, { retryCount: 0 }) });
+        const t0 = performance.now();
+        try {
+            await client.getBlockNumber();
+            const latencyMs = Math.max(0, Math.round(performance.now() - t0));
+            log(`[rpc] ${layer} ${host} ok latency=${latencyMs}ms`);
+            results.push({ ok: true, host, latencyMs });
+        }
+        catch (err) {
+            const failure = classifyProbeError(host, err);
+            if (failure.code !== undefined) {
+                log(`[rpc] ${layer} ${host} warn ${failure.code}`);
+            }
+            else {
+                log(`[rpc] ${layer} ${host} warn unreachable: ${failure.message.split('\n')[0]}`);
+            }
+            results.push(failure);
+        }
+    }
+    return results;
+}
+/**
+ * Boot-log summary line for a fallback chain, formatted per AC7:
+ *   `[rpc] L2 transport: fallback chain (N providers) — primary=<host>`
+ */
+export function summarizeFallbackChain(layer, urls) {
+    return `[rpc] ${layer} transport: ${describeFallbackChain(urls)}`;
+}
 //# sourceMappingURL=rpc-network.js.map

package/dist/preflight/rpc-network.js.map

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

package/dist/rpc/transport.d.ts

@@ -0,0 +1,145 @@
+/**
+ * RPC transport helper — builds a viem `fallback()` transport from a single
+ * URL, an array of URLs, or a comma-separated string. The substrate for issue
+ * #592 (multi-RPC fallback chain across daemon / relayer / indexer / CI).
+ *
+ * Design:
+ * - `parseRpcUrls` normalises `string | readonly string[]` to a deduplicated
+ *   non-empty array, splits comma-strings, trims, drops empties, and caps the
+ *   chain at {@link MAX_RPC_CHAIN_LENGTH} providers (extras are dropped with a
+ *   warning). Throws when no URLs remain.
+ * - `buildFallbackTransport` wraps `http(url)` per slot inside viem's
+ *   `fallback([...], { rank: false, retryCount: 0 })`. `rank: false` is
+ *   explicit — the issue's "Tenderly stays in slot 3" constraint requires
+ *   order preservation (no latency-based reshuffling). `retryCount: 0` keeps
+ *   the helper from doubling retries on top of the existing
+ *   `withRecoverableRetry` wrapper used by callers like the mech adapter.
+ * - On exhausted fall-through the helper rejects with `AllRpcsFailedError`,
+ *   which carries a structured `providers: readonly string[]` list of masked
+ *   hosts so callers and tests can assert on it.
+ * - `describeFallbackChain` formats the canonical AC7 boot-log summary line:
+ *   `fallback chain (N providers) — primary=<host>`.
+ *
+ * Do not conflate with `discovery.fallbackToOnchain` — that's a separate layer
+ * at the read-API level (Ponder → eth_getLogs floor). This helper sits beneath
+ * both layers at the JSON-RPC transport level.
+ */
+import { type FallbackTransport, type Transport } from 'viem';
+/**
+ * Hard cap on the number of providers in a single fallback chain. Four covers
+ * the "operator paid primary + public publicnode + public sepolia.base.org +
+ * Tenderly slot-3" shape from the issue; beyond that the boot probe takes too
+ * long and slot 5+ is almost always copy-paste noise.
+ */
+export declare const MAX_RPC_CHAIN_LENGTH = 4;
+export interface ParseRpcUrlsOptions {
+    /** Logger used to emit the "capped" warning. Defaults to `console.error`. */
+    log?: (message: string) => void;
+}
+/**
+ * Normalise `string | readonly string[]` into a non-empty, deduplicated,
+ * capped list of RPC URLs. Comma-separated strings are split (operator
+ * convention, see `peers` in `config.ts`). Duplicates are removed before the
+ * cap is applied so the effective chain length matches operator intent (an
+ * operator who prepends their paid primary to the existing fallback list
+ * shouldn't burn a slot on the duplicate).
+ *
+ * @throws if the input yields zero non-empty URLs.
+ */
+export declare function parseRpcUrls(input: string | readonly string[], options?: ParseRpcUrlsOptions): string[];
+/**
+ * Error thrown when every provider in a fallback chain has failed. Carries
+ * the masked host list so callers can surface a useful operator-facing message
+ * without leaking secret query strings (api-key paths).
+ */
+export declare class AllRpcsFailedError extends Error {
+    readonly providers: readonly string[];
+    readonly cause?: unknown;
+    constructor(providers: readonly string[], cause?: unknown);
+}
+/**
+ * Detect errors that viem's `fallback()` short-circuits on (via its
+ * `shouldThrow(err)` fast-exit) — `ExecutionRevertedError`,
+ * `TransactionRejectedRpcError`, `UserRejectedRequestError`,
+ * `WalletConnectSessionSettlementError`, and CAIP user-rejected (code
+ * `5000`). These are EVM- or wallet-level signals, NOT transport-level
+ * failures, so they must propagate unchanged. Wrapping them as
+ * `AllRpcsFailedError` would give the operator-app a false-positive
+ * "all RPCs failed" message when the actual problem is e.g. a contract
+ * revert on a view function.
+ *
+ * Mirrors viem's own predicate at
+ * `node_modules/viem/clients/transports/fallback.ts` (`shouldThrow`),
+ * dispatching by **numeric JSON-RPC code** (the path that catches real
+ * `RpcRequestError` instances coming out of the HTTP transport) plus the
+ * `ExecutionRevertedError.nodeMessage` regex (the path that catches reverts
+ * surfaced as plain `Error` with no numeric code). The cause-chain walk by
+ * class `name` remains as a third path for wallet-provider stacks that
+ * deliver proper class instances (and for already-normalised errors after
+ * viem's `buildRequest` re-wrap pass).
+ */
+export declare function isViemShouldThrowError(err: unknown): boolean;
+/**
+ * Default cooldown applied to a slot that returns a quota / rate-limit error
+ * (#835). After this window the demoted slot becomes eligible again rather than
+ * being permanently disabled (AC2), so a transient 429 / monthly-quota blip
+ * never strands an operator on a degraded provider for the rest of the process.
+ */
+export declare const DEFAULT_RPC_COOLDOWN_MS = 60000;
+/**
+ * Detect quota / rate-limit errors from an RPC provider (#835). Unlike
+ * {@link isViemShouldThrowError} (which marks EVM/wallet-level signals that must
+ * NOT trigger fallback), a quota error means the *slot* is temporarily unusable
+ * and should be demoted behind healthy slots for a cooldown window. Walks the
+ * cause chain (cycle-safe, mirroring `isViemShouldThrowError`) and matches on:
+ *  - HTTP `status === 429` (the `http()` transport's `HttpRequestError`);
+ *  - JSON-RPC `code === LimitExceededRpcError.code` (-32005);
+ *  - a narrow message regex backstop covering unambiguous provider phrasings
+ *    ("rate limit", "too many requests", "429", "quota", "compute unit",
+ *    "request rate", "throughput") — deliberately excluding the ambiguous
+ *    "limit"/"exceeded" words that collide with gas-limit errors.
+ *
+ * Deliberately narrow: a 5xx / network error is NOT a quota error (it falls
+ * through via viem but does not cool the slot — AC3 keeps static order when no
+ * quota errors occur), and a contract revert (code 3) is never a quota error.
+ */
+export declare function isRpcQuotaError(err: unknown): boolean;
+/**
+ * Mask an RPC URL down to its hostname for display / error reporting. Drops
+ * the path so api-key segments in the URL don't leak into logs.
+ */
+export declare function maskRpcHost(url: string): string;
+export interface BuildFallbackTransportOptions {
+    /**
+     * Set to `true` to let viem rank providers by latency. Default `false` —
+     * order matters for operator-configured paid primaries and the
+     * "Tenderly stays in slot 3" constraint from the issue.
+     */
+    rank?: boolean;
+    /**
+     * Injectable clock for the quota-cooldown bookkeeping (#835). Defaults to
+     * {@link Date.now}. Tests pass a controllable stub so cooldown expiry (AC2)
+     * is deterministic without real timers.
+     */
+    now?: () => number;
+    /**
+     * How long a slot stays demoted after a quota / rate-limit error, in ms
+     * (#835). Defaults to {@link DEFAULT_RPC_COOLDOWN_MS}.
+     */
+    cooldownMs?: number;
+}
+/**
+ * Build a viem fallback transport over the given URLs. Returns a callable
+ * transport suitable for `createPublicClient({ transport })`.
+ *
+ * Errors that exhaust the chain are wrapped in `AllRpcsFailedError`.
+ */
+export declare function buildFallbackTransport(urls: readonly string[], options?: BuildFallbackTransportOptions): FallbackTransport;
+export declare namespace buildFallbackTransport {
+    var buildFromTransports: (transports: readonly Transport[], urls: readonly string[], options?: BuildFallbackTransportOptions) => FallbackTransport;
+}
+/**
+ * Boot-log summary line for a fallback chain. Matches the canonical AC7
+ * format: `fallback chain (N providers) — primary=<host>`.
+ */
+export declare function describeFallbackChain(urls: readonly string[]): string;