@jinn-network/client 0.1.6 → 0.1.7-canary.08ebd916

package/dist/discovery/types.d.ts

@@ -145,6 +145,36 @@ export interface DiscoveryAPI {
      * `undefined` if no lifecycle events have been recorded for it yet.
      */
     getLifecycleStatus(manifestCid: string): Promise<SolverNetLifecycleStatus | undefined>;
+    /**
+     * Returns the number of distinct operators that have *ever* claimed a task
+     * on the SolverNet identified by `manifestCid` — i.e. the count of unique
+     * `attempt.operator` Safe addresses across every task whose
+     * `manifestDigest === keccak256(manifestCid)`, **including tasks that are
+     * now finalized or refunded**.
+     *
+     * This is an *ever-participated* signal, not a "currently active" one. The
+     * count never filters on task lifecycle state: the on-chain backing reads
+     * raw `TaskAttemptCreated` logs, which carry no finalized/refunded flag, so
+     * the only count consistent across all three backings (HTTP / embedded /
+     * on-chain) is the all-time distinct-operator total. Treat it as "operators
+     * who have participated at least once", not "operators participating today".
+     *
+     * It is the protocol-observable participation signal: a "join" in the
+     * operator app is purely a local config write (`joinedSolverNets[<cid>]`,
+     * see `spec/2026-05-05-solvernet-creation-and-launch.md` §12) and leaves no
+     * on-chain footprint. An operator only becomes visible to the network once
+     * they claim a task — `TaskAttemptCreated` is the first on-chain event tied
+     * to (operator, SolverNet). This method therefore counts *participating*
+     * operators (operators who have claimed at least one task), which is the
+     * only honest cross-operator count derivable from the indexer / chain.
+     *
+     * Task pagination is hard-capped (`MAX_OPERATOR_COUNT_TASK_PAGES` in each
+     * backing) so a pathological task volume cannot turn this into an unbounded
+     * scan; on a SolverNet beyond the cap the count is a lower bound.
+     *
+     * Returns `0` when no operator has attempted a task on the SolverNet yet.
+     */
+    getSolverNetOperatorCount(manifestCid: string): Promise<number>;
     /**
      * Returns envelope refs matching the query. Refs only — byte retrieval is
      * done by the corpus library on demand.
@@ -191,6 +221,36 @@ export interface DiscoveryAPI {
         builderAgentId: string;
         limit?: number;
     }): Promise<PublishedArtifact[]>;
+    /**
+     * Returns network-truth pass counts per swe-rebench-v2 instance_id for a
+     * given SolverNet manifest. Keyed by `instance_id`; the value is the count
+     * of distinct (requestId, chainId) verdictEnvelopeMeta rows where
+     * `solverNetManifestCid` equals `args.manifestCid`, `actualPassed = true`,
+     * `solverType` starts with `swe-rebench-v2`, and `instanceId` is non-empty.
+     *
+     * Per-SolverNet scoping (#669 Finding 2): the indexer enrichment pass reads
+     * the task body's top-level `solverNetManifestCid` (task.v1 schema; see
+     * `client/src/types/task-document.ts`) on the same IPFS round-trip that
+     * resolves `instance_id`, and writes it to `verdictEnvelopeMeta`. The
+     * GraphQL filter pins to that column, so multi-SolverNet operators with
+     * overlapping instance_id pools do NOT cross-tenant over-count — successes
+     * on SolverNet-B can no longer prematurely saturate SolverNet-A's launcher.
+     *
+     * Backed by `verdictEnvelopeMeta` in the indexer. Throws
+     * `DiscoveryUnavailableError` when the backing is unreachable — callers
+     * MUST NOT silently fall through to local-only counts (#669 acceptance
+     * criterion: behave as if the on-chain count is the truth). The
+     * `withFallback` wrapper enforces this by never routing
+     * `getInstanceSuccessCounts` to the floor.
+     *
+     * The on-chain floor implementation (`OnchainDiscoveryAPI`) returns an
+     * empty Map, since the underlying data comes from IPFS enrichment that the
+     * floor cannot reconstruct. The floor's empty Map is therefore not the
+     * runtime path — `withFallback` propagates the error instead.
+     */
+    getInstanceSuccessCounts(args: {
+        manifestCid: string;
+    }): Promise<Map<string, number>>;
 }
 /**
  * Thrown by a DiscoveryAPI implementation when it is temporarily unable to
@@ -200,7 +260,21 @@ export interface DiscoveryAPI {
  * The `withFallback` wrapper catches this class (plus network-shaped errors)
  * and routes to the floor implementation for the duration of the outage.
  */
+/**
+ * Machine-readable reason a discovery read failed. `rpc_rate_limited` is the
+ * one branch callers act on distinctly: it means the configured RPC endpoint
+ * returned a 429 (or otherwise rate-limited the daemon), which — on the shared
+ * default RPC — is an operator-actionable condition ("add your own key"), not
+ * an indexer outage. Any other transport failure is left untyped (`undefined`).
+ */
+export type DiscoveryUnavailableCode = 'rpc_rate_limited';
 export declare class DiscoveryUnavailableError extends Error {
     readonly cause?: unknown;
-    constructor(message: string, cause?: unknown);
+    /**
+     * Typed reason, when one can be classified — currently only
+     * `rpc_rate_limited`, surfaced end-to-end so the operator UI can render a
+     * distinct "your RPC is throttled" message instead of a generic failure.
+     */
+    readonly code?: DiscoveryUnavailableCode;
+    constructor(message: string, cause?: unknown, code?: DiscoveryUnavailableCode);
 }

package/dist/discovery/types.js

@@ -9,21 +9,19 @@
  *
  * Spec: spec/2026-05-11-discovery-api-and-shared-indexer.md §5.
  */
-// ── Error ────────────────────────────────────────────────────────────────────
-/**
- * Thrown by a DiscoveryAPI implementation when it is temporarily unable to
- * serve a request — e.g. indexer unreachable, embedded Ponder still syncing,
- * hosted subgraph 5xx.
- *
- * The `withFallback` wrapper catches this class (plus network-shaped errors)
- * and routes to the floor implementation for the duration of the outage.
- */
 export class DiscoveryUnavailableError extends Error {
     cause;
-    constructor(message, cause) {
+    /**
+     * Typed reason, when one can be classified — currently only
+     * `rpc_rate_limited`, surfaced end-to-end so the operator UI can render a
+     * distinct "your RPC is throttled" message instead of a generic failure.
+     */
+    code;
+    constructor(message, cause, code) {
         super(message);
         this.name = 'DiscoveryUnavailableError';
         this.cause = cause;
+        this.code = code;
     }
 }
 //# sourceMappingURL=types.js.map

package/dist/discovery/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/discovery/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgOH,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAChC,KAAK,CAAW;IAElC,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/discovery/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAiTH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAChC,KAAK,CAAW;IAClC;;;;OAIG;IACM,IAAI,CAA4B;IAEzC,YAAY,OAAe,EAAE,KAAe,EAAE,IAA+B;QAC3E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/discovery/with-fallback.d.ts

@@ -12,6 +12,13 @@
  * operators can see why their daemon is running slowly. After the window
  * elapses the wrapper probes the primary again on the next call.
  *
+ * NOTE (2026-05-23): this wrapper is no longer engaged by default. The
+ * factory installs it only when `discovery.fallbackToOnchain === true` (an
+ * explicit opt-in). Without the opt-in, indexer outages propagate as
+ * DiscoveryUnavailableError so the operator-app surfaces them rather than the
+ * daemon silently storming shared RPC. The wrapper itself is unchanged for
+ * operators who still want it.
+ *
  * Spec: spec/2026-05-11-discovery-api-and-shared-indexer.md §9.3.
  */
 import type { DiscoveryAPI } from './types.js';

package/dist/discovery/with-fallback.js

@@ -12,6 +12,13 @@
  * operators can see why their daemon is running slowly. After the window
  * elapses the wrapper probes the primary again on the next call.
  *
+ * NOTE (2026-05-23): this wrapper is no longer engaged by default. The
+ * factory installs it only when `discovery.fallbackToOnchain === true` (an
+ * explicit opt-in). Without the opt-in, indexer outages propagate as
+ * DiscoveryUnavailableError so the operator-app surfaces them rather than the
+ * daemon silently storming shared RPC. The wrapper itself is unchanged for
+ * operators who still want it.
+ *
  * Spec: spec/2026-05-11-discovery-api-and-shared-indexer.md §9.3.
  */
 import { DiscoveryUnavailableError } from './types.js';
@@ -145,6 +152,9 @@ export function withFallback(primary, floor, opts = {}) {
         getLifecycleStatus(manifestCid) {
             return dispatch(() => primary.getLifecycleStatus(manifestCid), () => floor.getLifecycleStatus(manifestCid));
         },
+        getSolverNetOperatorCount(manifestCid) {
+            return dispatch(() => primary.getSolverNetOperatorCount(manifestCid), () => floor.getSolverNetOperatorCount(manifestCid));
+        },
         queryEnvelopes(query) {
             return dispatch(() => primary.queryEnvelopes(query), () => floor.queryEnvelopes(query));
         },
@@ -157,6 +167,16 @@ export function withFallback(primary, floor, opts = {}) {
         listBuilderArtifacts(args) {
             return dispatch(() => primary.listBuilderArtifacts(args), () => floor.listBuilderArtifacts(args));
         },
+        getInstanceSuccessCounts(args) {
+            // Never fall through to the floor for this method — an empty Map from
+            // the floor is indistinguishable from "all instances have 0 successes",
+            // which is the under-count bug this method was introduced to fix (#669).
+            // If the primary is degraded, propagate the error so the launcher aborts
+            // its tick rather than silently posting against local-only counters.
+            // The DiscoveryAPI.getInstanceSuccessCounts JSDoc encodes this contract
+            // ("callers MUST NOT silently fall through to local-only counts").
+            return primary.getInstanceSuccessCounts(args);
+        },
     };
 }
 //# sourceMappingURL=with-fallback.js.map

package/dist/discovery/with-fallback.js.map

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

package/dist/earning/bootstrap.d.ts

@@ -4,8 +4,78 @@
  * Phase 1 (master): generate mnemonic → fund master EOA
  * Phase 2 (per-service): derive agent → stake → deploy mech
  */
-import type { FleetState, FleetBootstrapResult } from './types.js';
+import type { FleetState, FleetBootstrapResult, StakingMode } from './types.js';
 import { requestTestnetFunding } from './faucet.js';
+import { type JinnOnchainNetwork } from './viem-clients.js';
+/**
+ * 2× cold-start headroom for master ETH target on a fresh bootstrap.
+ *
+ * Gas accounting for a single standard-mode service on first run:
+ *   ~1.3M gas for the Safe deploy + stake + mech (at 2 gwei ≈ 0.0026 ETH)
+ *   + 0.002 ETH Safe seed (sent to the Safe so it can pay mech fees)
+ *   ≈ 0.0046 ETH minimum; 2× gives ≈ 0.009–0.010 ETH — the bootstrap
+ *   `minEoaGasEth` default.
+ *
+ * Used by {@link stage1MinMasterEth} to size the Stage 1 master gas budget.
+ *
+ * Single source of truth: imported by funding-plan.ts.
+ */
+export declare const STANDARD_MASTER_BOOTSTRAP_MULTIPLIER = 2n;
+/**
+ * Self-bond mode needs much more ETH per service than standard mode because
+ * the master funds the agent which then pays for: Safe deploy, 5 service
+ * registry txs (create, activate, register, deploy, stake), and mech deploy.
+ * Roughly 15 txs at varying gas costs. 0.03 ETH per service is a safe
+ * estimate. Single source of truth: imported by funding-plan.ts.
+ */
+export declare const SELF_BOND_ETH_PER_SERVICE = 30000000000000000n;
+/**
+ * Single source of truth for the master-ETH cold-start funding gate.
+ *
+ * Both the mutating bootstrapper ({@link FleetBootstrapper.ensureStage1And2})
+ * and the read-only funding plan (`planFleetFunding` in funding-plan.ts) route
+ * through this helper, so a migration-wiped fleet computes an identical
+ * required-ETH gate in both views. Re-implementing the gate inline at either
+ * call site is the u34i cross-module invariant-drift hazard — do not do it.
+ *
+ * Standard-mode gate has three branches:
+ *   1. `standardFleetAlreadyComplete` — fleet already has its full target of
+ *      operational services and no deprecated-setup migration is pending →
+ *      `0n` (nothing to fund).
+ *   2. `preStage1` — no fleet identity yet (`fleet_stage === 'none'` or no
+ *      fleet state at all) → the Stage 1 gate from {@link stage1MinMasterEth},
+ *      which covers the master → agent transfer plus the master's own gas
+ *      reserve. See jinn-mono-u34i.
+ *   3. otherwise — the Stage 2 master gas budget: `minEoaGasEth` (stake gas)
+ *      plus a per-extra-service top-up transfer for services 2..N.
+ *
+ * Self-bond mode is a flat `SELF_BOND_ETH_PER_SERVICE × targetServices`
+ * regardless of stage.
+ *
+ * @param services         Persisted service states
+ * @param minEoaGasEth     Configured minimum EOA gas target (wei)
+ * @param pendingSetupMigration  True when a deprecated testnet setup is
+ *   detected — suppresses the `standardFleetAlreadyComplete` short-circuit so a
+ *   migration-wiped fleet is correctly treated as needing funding. Both call
+ *   sites MUST pass this so the bootstrapper gate and the funding-plan view
+ *   agree for migration-wiped fleets.
+ * @param targetServices   How many services the fleet is aiming for
+ * @param stakingMode      `'standard'` (default) or `'self-bond'`
+ * @param preStage1        True when fleet identity is not yet provisioned —
+ *   selects the Stage 1 gate. The bootstrapper passes `false` here because it
+ *   only computes this gate *after* `ensureStage1` succeeds.
+ */
+export declare function computeRequiredMasterEth({ services, minEoaGasEth, pendingSetupMigration, targetServices, stakingMode, preStage1, }: {
+    services: Array<{
+        service_id?: number | null | undefined;
+        step?: string;
+    }>;
+    minEoaGasEth: bigint;
+    pendingSetupMigration?: boolean;
+    targetServices?: number;
+    stakingMode?: StakingMode;
+    preStage1?: boolean;
+}): bigint;
 /** Master ETH required to FINISH the whole bootstrap from a fresh start (not
  *  just to enter Stage 1). Centralized so the daemon's ensureStage1 gate,
  *  the read-side funding-plan, gather-status, and the panel faucet target
@@ -62,8 +132,9 @@ export interface FleetBootstrapperOptions {
     /** Optional Safe ETH target override (wei). */
     minSafeEthWei?: string;
     /**
-     * When `masterEthDailyEstimateWei` is unset, blends a conservative daily estimate
-     * from poll frequency (config.pollIntervalMs).
+     * Daemon poll interval. Currently unused by the master-daily-estimate path
+     * (the poll-based blend was removed in #288); kept on the options bag so
+     * existing callers compile unchanged.
      */
     pollIntervalMs?: number;
     /**
@@ -139,7 +210,11 @@ export declare class FleetBootstrapper {
      */
     private bindAgentWalletWithRetry;
     /**
-     * Conservative daily master gas (wei): max(DEFAULT, rough tx count from poll interval × cost).
+     * Conservative daily master gas (wei). Returns the floor; operators who
+     * want a more aggressive estimate can still set `JINN_MASTER_ETH_DAILY_WEI`.
+     * See DEFAULT_MASTER_ETH_DAILY_WEI for rationale (#288). The
+     * `pollIntervalMs` parameter is vestigial since the poll-based blend was
+     * removed; kept so the constructor call site stays unchanged.
      */
     private estimateMasterDailyGasWei;
     /**
@@ -286,3 +361,24 @@ export declare class FleetBootstrapper {
 }
 /** @deprecated Use FleetBootstrapper */
 export declare const EarningBootstrapper: typeof FleetBootstrapper;
+export interface RecoverEvictedServiceOptions {
+    /** Display index of the service (used only for log messages). */
+    serviceDisplayIndex: number;
+    serviceId: number;
+    stakingAddress: string;
+    distributorAddress: string;
+    rpcUrl: string;
+    chain: JinnOnchainNetwork;
+    mnemonic: string;
+}
+/**
+ * Re-stake an evicted service by calling `distributor.reStake(stakingProxy, serviceId)`.
+ *
+ * Extracted from `FleetBootstrapper.recoverEvictedService` so it can be called
+ * from the in-process `EvictionLoop` without requiring a full bootstrapper
+ * context (jinn-mono-hjex.3).
+ *
+ * The caller is responsible for advancing the local service step back to
+ * `mech_deployed` after this returns (just like the bootstrapper resume path does).
+ */
+export declare function recoverEvictedService(opts: RecoverEvictedServiceOptions): Promise<void>;