@jinn-network/client 0.1.6 → 0.1.7-canary.17a8ecb8

package/dist/restart-daemon.d.ts

@@ -0,0 +1,90 @@
+/**
+ * In-process respawn helper for operator-triggered daemon restarts.
+ *
+ * Issue #289 added respawn-instead-of-exit so the operator panel survives a
+ * restart click. Issue #561 fixed the follow-on bug: the original respawn
+ * spawned the child *before* the parent had released its server sockets, so
+ * the child raced into `.listen(7332)` while the parent still held the port
+ * and died with EADDRINUSE / exitCode 11. The fix is `preSpawnCleanup` — an
+ * async hook the caller uses to close API + OTLP receivers before the child
+ * is spawned. With cleanup in place the port is free synchronously and the
+ * child binds on first try; without it (older callers, tests) the helper
+ * behaves as before.
+ *
+ * Every restart-required config change funnels through the same handler:
+ *
+ *   - POST /v1/setup/network              — RPC URL change
+ *   - POST /v1/setup/change-password      — keystore password rotation
+ *   - POST /v1/setup/solvernets/:name     — SolverNet enable/disable
+ *   - POST /v1/operator/join/:cid         — SolverNet join
+ *
+ * Headless gate: `JINN_NO_UI=1` (already the established headless flag in
+ * main.ts) skips the respawn — operators running `jinn run --no-ui` from a
+ * supervisor / systemd unit / docker entrypoint want the supervisor to
+ * decide whether to restart, not the daemon.
+ *
+ * The helper is split out from main.ts so it's unit-testable without
+ * touching the entry-point bootstrap path.
+ */
+import { spawn } from 'node:child_process';
+/**
+ * Options for `requestDaemonRestart`. All optional in production; the helper
+ * defaults to `process` / `node:child_process`. Tests inject doubles.
+ */
+export interface RequestDaemonRestartOptions {
+    /** Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Defaults to `process.argv` (`[node, scriptPath, ...args]`). */
+    argv?: readonly string[];
+    /** Defaults to `process.execPath` (the node binary). */
+    execPath?: string;
+    /**
+     * Defaults to `node:child_process.spawn`. Injected for tests so we can
+     * assert what was spawned without actually forking node.
+     */
+    spawnFn?: typeof spawn;
+    /** Defaults to `(code) => process.exit(code)`. Injected for tests. */
+    exitFn?: (code: number) => void;
+    /** Defaults to `console.log`. Injected for tests to capture output. */
+    log?: (message: string) => void;
+    /**
+     * Delay (ms) between spawning the child and exiting the parent. Gives the
+     * child a moment to bind the API port before the parent vacates it.
+     * Defaults to 250ms per the issue body. Tests can pass 0 for synchrony.
+     */
+    exitDelayMs?: number;
+    /**
+     * Bypass the headless gate. The operator-dashboard Restart button passes
+     * this — when the operator clicks Restart, they explicitly want the
+     * daemon to come back, even under a supervisor. Supervisor-driven
+     * restart flows (MCP tools, signals) leave this `false` so the
+     * supervisor stays in charge.
+     */
+    forceRespawn?: boolean;
+    /**
+     * Optional async hook run *before* the replacement child is spawned. The
+     * caller uses this to close listening sockets the child will need to
+     * bind — API server (7332) and OTLP receiver (4317/4318) — so the child
+     * doesn't lose an EADDRINUSE race with the parent. Errors are caught and
+     * logged; the respawn still proceeds because leaving the operator
+     * stranded is worse than a noisy close. Skipped in headless mode.
+     */
+    preSpawnCleanup?: () => Promise<void>;
+}
+/**
+ * Pure predicate: true when the current env is headless and respawn should
+ * be skipped. Exposed so callers and tests can share the same check.
+ */
+export declare function isHeadless(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Handle an operator-triggered restart request.
+ *
+ * - In **interactive** mode (default), spawn a detached child that re-runs
+ *   the current node invocation, then exit after a short delay so the child
+ *   can bind the API port.
+ * - In **headless** mode (`JINN_NO_UI=1`), exit without respawning. The
+ *   supervisor is responsible for relaunching the daemon if it wants to.
+ *
+ * Returns the action taken (for tests). Production callers ignore the return.
+ */
+export declare function requestDaemonRestart(opts?: RequestDaemonRestartOptions): Promise<'respawned' | 'headless-exit'>;

package/dist/restart-daemon.js

@@ -0,0 +1,95 @@
+/**
+ * In-process respawn helper for operator-triggered daemon restarts.
+ *
+ * Issue #289 added respawn-instead-of-exit so the operator panel survives a
+ * restart click. Issue #561 fixed the follow-on bug: the original respawn
+ * spawned the child *before* the parent had released its server sockets, so
+ * the child raced into `.listen(7332)` while the parent still held the port
+ * and died with EADDRINUSE / exitCode 11. The fix is `preSpawnCleanup` — an
+ * async hook the caller uses to close API + OTLP receivers before the child
+ * is spawned. With cleanup in place the port is free synchronously and the
+ * child binds on first try; without it (older callers, tests) the helper
+ * behaves as before.
+ *
+ * Every restart-required config change funnels through the same handler:
+ *
+ *   - POST /v1/setup/network              — RPC URL change
+ *   - POST /v1/setup/change-password      — keystore password rotation
+ *   - POST /v1/setup/solvernets/:name     — SolverNet enable/disable
+ *   - POST /v1/operator/join/:cid         — SolverNet join
+ *
+ * Headless gate: `JINN_NO_UI=1` (already the established headless flag in
+ * main.ts) skips the respawn — operators running `jinn run --no-ui` from a
+ * supervisor / systemd unit / docker entrypoint want the supervisor to
+ * decide whether to restart, not the daemon.
+ *
+ * The helper is split out from main.ts so it's unit-testable without
+ * touching the entry-point bootstrap path.
+ */
+import { spawn } from 'node:child_process';
+/**
+ * Pure predicate: true when the current env is headless and respawn should
+ * be skipped. Exposed so callers and tests can share the same check.
+ */
+export function isHeadless(env = process.env) {
+    return env['JINN_NO_UI'] === '1';
+}
+/**
+ * Handle an operator-triggered restart request.
+ *
+ * - In **interactive** mode (default), spawn a detached child that re-runs
+ *   the current node invocation, then exit after a short delay so the child
+ *   can bind the API port.
+ * - In **headless** mode (`JINN_NO_UI=1`), exit without respawning. The
+ *   supervisor is responsible for relaunching the daemon if it wants to.
+ *
+ * Returns the action taken (for tests). Production callers ignore the return.
+ */
+export async function requestDaemonRestart(opts = {}) {
+    const env = opts.env ?? process.env;
+    const argv = opts.argv ?? process.argv;
+    const execPath = opts.execPath ?? process.execPath;
+    const spawnFn = opts.spawnFn ?? spawn;
+    const exitFn = opts.exitFn ?? ((code) => process.exit(code));
+    const log = opts.log ?? ((message) => console.log(message));
+    const exitDelayMs = opts.exitDelayMs ?? 250;
+    if (isHeadless(env) && !opts.forceRespawn) {
+        log('[main] Restart requested via operator MCP, but JINN_NO_UI=1 — exiting without respawn (let the supervisor decide).');
+        exitFn(0);
+        return 'headless-exit';
+    }
+    log('[main] Restart requested via operator MCP. Spawning replacement and exiting...');
+    // jinn-mono #561: release server sockets BEFORE the child spawns. Without
+    // this, the child loses an EADDRINUSE race on 7332 (and OTLP 4317/4318)
+    // and dies with exitCode 11 before it can take over.
+    if (opts.preSpawnCleanup) {
+        try {
+            await opts.preSpawnCleanup();
+        }
+        catch (err) {
+            log(`[main] preSpawnCleanup error (proceeding with respawn anyway): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // argv[0] is the node binary; argv[1..] are the script + flags. The child
+    // re-runs the same script with the same flags, under the same node binary.
+    const childArgs = argv.slice(1);
+    const spawnOptions = {
+        detached: true,
+        stdio: 'inherit',
+        env,
+    };
+    const child = spawnFn(execPath, childArgs, spawnOptions);
+    // Detach so the parent can exit without taking the child with it.
+    child.unref();
+    // With preSpawnCleanup the port is already free; the small delay is kept
+    // as a paranoid belt-and-suspenders against any kernel-level lingering on
+    // SO_LINGER-disabled sockets. Tests pass 0.
+    if (exitDelayMs <= 0) {
+        exitFn(0);
+    }
+    else {
+        setTimeout(() => exitFn(0), exitDelayMs);
+    }
+    return 'respawned';
+}
+//# sourceMappingURL=restart-daemon.js.map

package/dist/restart-daemon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart-daemon.js","sourceRoot":"","sources":["../src/restart-daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAC;AA+C9D;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,OAAO,GAAG,CAAC,YAAY,CAAC,KAAK,GAAG,CAAC;AACnC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAoC,EAAE;IAEtC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IACnD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC;IACtC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACrE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACpE,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,GAAG,CAAC;IAE5C,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;QAC1C,GAAG,CACD,oHAAoH,CACrH,CAAC;QACF,MAAM,CAAC,CAAC,CAAC,CAAC;QACV,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,GAAG,CAAC,gFAAgF,CAAC,CAAC;IAEtF,0EAA0E;IAC1E,wEAAwE;IACxE,qDAAqD;IACrD,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CACD,kEACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;QACJ,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,2EAA2E;IAC3E,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,YAAY,GAAiB;QACjC,QAAQ,EAAE,IAAI;QACd,KAAK,EAAE,SAAS;QAChB,GAAG;KACJ,CAAC;IACF,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IACzD,kEAAkE;IAClE,KAAK,CAAC,KAAK,EAAE,CAAC;IAEd,yEAAyE;IACzE,0EAA0E;IAC1E,4CAA4C;IAC5C,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACrB,MAAM,CAAC,CAAC,CAAC,CAAC;IACZ,CAAC;SAAM,CAAC;QACN,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}

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,