@jinn-network/client 0.1.7 → 0.1.8

package/dist/preflight/pidfile-liveness.js

@@ -0,0 +1,103 @@
+/**
+ * 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' }
+ *   - 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' }
+ *
+ * `.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' };
+    }
+    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":"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"}

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,109 @@
+/**
+ * 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;
+/**
+ * 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;
+}
+/**
+ * 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;

package/dist/rpc/transport.js

@@ -0,0 +1,220 @@
+/**
+ * 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 { ExecutionRevertedError, fallback, http, TransactionRejectedRpcError, UserRejectedRequestError, } 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 const MAX_RPC_CHAIN_LENGTH = 4;
+/**
+ * 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 function parseRpcUrls(input, options = {}) {
+    const log = options.log ?? ((m) => process.stderr.write(`${m}\n`));
+    const raw = typeof input === 'string' ? input.split(',') : [...input];
+    const cleaned = raw.map((u) => u.trim()).filter((u) => u.length > 0);
+    if (cleaned.length === 0) {
+        throw new Error('parseRpcUrls: at least one RPC URL is required');
+    }
+    // Dedup before applying the cap so repeated URLs (easy to introduce when an
+    // operator prepends a paid primary that already exists in the fallback list)
+    // don't burn slots of the 4-slot chain. `Set` preserves first-seen insertion
+    // order, which matches the "primary stays in slot 0" constraint.
+    const deduped = [...new Set(cleaned)];
+    if (deduped.length > MAX_RPC_CHAIN_LENGTH) {
+        log(`[rpc] capped fallback chain to ${MAX_RPC_CHAIN_LENGTH} providers ` +
+            `(dropped ${deduped.length - MAX_RPC_CHAIN_LENGTH} extra slots)`);
+        return deduped.slice(0, MAX_RPC_CHAIN_LENGTH);
+    }
+    return deduped;
+}
+/**
+ * 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 class AllRpcsFailedError extends Error {
+    providers;
+    cause;
+    constructor(providers, cause) {
+        super(`All RPC providers in the fallback chain failed (providers=${providers.join(', ')})`);
+        this.name = 'AllRpcsFailedError';
+        this.providers = providers;
+        this.cause = cause;
+    }
+}
+/**
+ * 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 function isViemShouldThrowError(err) {
+    // 1. Code-based dispatch — matches what viem's own `shouldThrow` does,
+    //    so a raw `RpcRequestError { code: 3 | -32003 | 4001 | 7000 | 5000 }`
+    //    from the HTTP transport is caught here regardless of class name.
+    //    Codes are pulled from the viem error classes (no magic numbers) where
+    //    available; 7000 and 5000 are inline because
+    //    `WalletConnectSessionSettlementError` is not re-exported from the
+    //    top-level `viem` package and 5000 is the CAIP user-rejected code
+    //    viem hard-codes alongside it.
+    if (err instanceof Error && 'code' in err && typeof err.code === 'number') {
+        const code = err.code;
+        if (code === ExecutionRevertedError.code || // 3 — contract revert
+            code === TransactionRejectedRpcError.code || // -32003 — tx rejected
+            code === UserRejectedRequestError.code || // 4001 — user-rejected
+            code === 7000 || // WalletConnectSessionSettlementError
+            code === 5000 // CAIP user-rejected
+        )
+            return true;
+        // 2. nodeMessage regex — catches reverts that arrive as a plain `Error`
+        //    (no numeric code, no recognised class name). Viem's own
+        //    `shouldThrow` runs this check too.
+        if (ExecutionRevertedError.nodeMessage.test(err.message))
+            return true;
+    }
+    // 3. Cause-chain walk — viem wraps low-level RPC errors in higher-level
+    //    error classes (e.g. `ContractFunctionExecutionError` →
+    //    `RpcRequestError` → `ExecutionRevertedError`), and wallet providers
+    //    can deliver proper class instances directly. Walk with cycle
+    //    detection so a self-referential `.cause` cannot infinite-loop.
+    const seen = new Set();
+    let cursor = err;
+    while (cursor instanceof Error && !seen.has(cursor)) {
+        seen.add(cursor);
+        if (cursor.name === 'ExecutionRevertedError')
+            return true;
+        if (cursor.name === 'TransactionRejectedRpcError')
+            return true;
+        if (cursor.name === 'UserRejectedRequestError')
+            return true;
+        if (cursor.name === 'WalletConnectSessionSettlementError')
+            return true;
+        cursor = cursor.cause;
+    }
+    return false;
+}
+/**
+ * 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 function maskRpcHost(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.hostname || '(unknown host)';
+    }
+    catch {
+        return '(invalid rpc url)';
+    }
+}
+/**
+ * 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 function buildFallbackTransport(urls, options = {}) {
+    const transports = urls.map((url) => http(url));
+    return buildFallbackTransport.buildFromTransports(transports, urls, options);
+}
+/**
+ * Internal helper exposed for tests: build a fallback transport from
+ * pre-constructed viem transports (e.g. `custom()` mocks) so tests can drive
+ * each slot deterministically without an actual HTTP fetch.
+ */
+buildFallbackTransport.buildFromTransports = function buildFromTransports(transports, urls, options = {}) {
+    const maskedProviders = urls.map(maskRpcHost);
+    const inner = fallback(transports, {
+        rank: options.rank ?? false,
+        retryCount: 0,
+    });
+    // Wrap the transport so that the final exhausted-chain rejection surfaces
+    // as our structured `AllRpcsFailedError` (carrying the masked host list).
+    // We do the wrap at the transport-factory level rather than swapping the
+    // returned function's `request` so the FallbackTransport's typed shape
+    // (`onResponse`, `transports`, etc.) is preserved.
+    const wrapped = ((config) => {
+        const t = inner(config);
+        const originalRequest = t.request.bind(t);
+        t.request = (async (args) => {
+            try {
+                return await originalRequest(args);
+            }
+            catch (err) {
+                // viem's fallback() short-circuits on shouldThrow-class errors
+                // (contract revert, user-rejected, CAIP 5000) — those are
+                // EVM/wallet-level, not transport-level failures. Propagate them
+                // unchanged so callers (and the operator-app's `rpc_all_failed`
+                // state message) don't misread a single-slot revert as an
+                // exhausted-chain outage.
+                if (isViemShouldThrowError(err))
+                    throw err;
+                // Otherwise: viem doesn't expose a distinct "all transports failed"
+                // error class — when fallback exhausts the chain it throws the last
+                // underlying error. Wrap so the caller gets a stable structural
+                // error carrying the masked provider list.
+                throw new AllRpcsFailedError(maskedProviders, err);
+            }
+        });
+        return t;
+    });
+    return wrapped;
+};
+/**
+ * Boot-log summary line for a fallback chain. Matches the canonical AC7
+ * format: `fallback chain (N providers) — primary=<host>`.
+ */
+export function describeFallbackChain(urls) {
+    if (urls.length === 0)
+        return 'fallback chain (0 providers)';
+    return `fallback chain (${urls.length} providers) — primary=${maskRpcHost(urls[0])}`;
+}
+//# sourceMappingURL=transport.js.map

package/dist/rpc/transport.js.map

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

package/dist/scripts/donation-consumption-acceptance.js

@@ -503,7 +503,6 @@ function buildConsumerHarnesses(raw) {
 }
 export function buildConsumerConfig(opts) {
     const clientHome = defaultClientHome(opts.consumerHome);
-    const solverNets = cloneSolverNetsForConsumer(opts.producerConfig.solverNets);
     const base = {
         network: opts.producerConfig.network ?? 'testnet',
         rpcUrl: opts.producerConfig.rpcUrl,
@@ -525,7 +524,8 @@ export function buildConsumerConfig(opts) {
         ...(opts.producerConfig.runtimeMode ? { runtimeMode: opts.producerConfig.runtimeMode } : {}),
         ...(opts.producerConfig.harness ? { harness: opts.producerConfig.harness } : {}),
         harnesses: buildConsumerHarnesses(opts.producerConfig.harnesses),
-        ...(solverNets ? { solverNets } : {}),
+        // Issue #421: the legacy `solverNets` block is retired; consumer config
+        // inherits the producer's `joinedSolverNets` only.
         ...(opts.producerConfig.joinedSolverNets ? { joinedSolverNets: opts.producerConfig.joinedSolverNets } : {}),
         engine: {
             workingDirRoot: join(clientHome, 'engine', 'work'),
@@ -582,22 +582,6 @@ export function ensureConsumerSweEvaluatorState(opts) {
     }
     return consumerStatePath;
 }
-function cloneSolverNetsForConsumer(raw) {
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
-        return undefined;
-    const out = {};
-    for (const [name, value] of Object.entries(raw)) {
-        if (!value || typeof value !== 'object' || Array.isArray(value))
-            continue;
-        const entry = { ...value };
-        const taskGenerator = entry.taskGenerator && typeof entry.taskGenerator === 'object' && !Array.isArray(entry.taskGenerator)
-            ? { ...entry.taskGenerator, enabled: false }
-            : { enabled: false };
-        entry.taskGenerator = taskGenerator;
-        out[name] = entry;
-    }
-    return Object.keys(out).length > 0 ? out : undefined;
-}
 function sourceName(value) {
     if (typeof value === 'string')
         return value;
@@ -628,16 +612,11 @@ function assertConsumerConfiguredForSwe(config, configPath) {
     const solverEntries = sweEntries.filter((entry) => (Array.isArray(entry.roles) && entry.roles.includes('solver')));
     const evaluatorEntries = sweEntries.filter((entry) => (Array.isArray(entry.roles) && entry.roles.includes('evaluator')));
     const joinedRuntimeEnabled = solverEntries.some((entry) => (!disablesSweRuntime(entry.disabledDefaultPlugins) || includesSweRuntimePlugin(entry.plugins)));
-    const solverNets = config.solverNets && typeof config.solverNets === 'object' && !Array.isArray(config.solverNets)
-        ? Object.values(config.solverNets)
-        : [];
-    const legacySweEntries = solverNets.filter((entry) => (entry.enabled !== false && entry.solverType === 'swe-rebench-v2.v1'));
-    const legacyHasSolver = legacySweEntries.some((entry) => (!Array.isArray(entry.roles) || entry.roles.includes('solving')));
-    const legacyHasEvaluator = legacySweEntries.some((entry) => (Array.isArray(entry.roles) && entry.roles.includes('evaluating')));
-    const legacyRuntimeEnabled = legacySweEntries.some((entry) => includesSweRuntimePlugin(entry.plugins));
-    const hasSolver = solverEntries.length > 0 || legacyHasSolver;
-    const hasEvaluator = evaluatorEntries.length > 0 || legacyHasEvaluator;
-    const runtimeEnabled = joinedRuntimeEnabled || legacyRuntimeEnabled;
+    // Issue #421: legacy `solverNets` is retired; SWE-rebench v2 SolverNet
+    // membership is asserted via joinedSolverNets exclusively.
+    const hasSolver = solverEntries.length > 0;
+    const hasEvaluator = evaluatorEntries.length > 0;
+    const runtimeEnabled = joinedRuntimeEnabled;
     if (!hasSolver || !hasEvaluator || !runtimeEnabled) {
         fail('consumer_swe_join_required', 'Consumer config is not joined to SWE-rebench v2 for the live donation gate.', {
             configPath,