@jinn-network/client 0.1.5 → 0.1.6-canary.107ea271

package/dist/earning/bootstrap.d.ts

@@ -6,6 +6,80 @@
  */
 import type { FleetState, FleetBootstrapResult } 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.
+ *
+ * The multiplier only applies when no service has a persisted `service_id`
+ * on-chain (i.e. the fleet is truly cold — OR migration-wiped, where
+ * services exist in shape but lost their on-chain anchor). Once any service
+ * has committed a `service_id`, the fleet is past the cold-start cliff and
+ * 1× suffices.
+ *
+ * Single source of truth: imported by funding-plan.ts.
+ */
+export declare const STANDARD_MASTER_BOOTSTRAP_MULTIPLIER = 2n;
+/**
+ * Compute the required master ETH gate for the standard staking mode.
+ *
+ * @param services         Persisted service states
+ * @param minEoaGasEth     Configured minimum EOA gas target (wei)
+ * @param standardMultiplier  Cold-start multiplier (defaults to {@link STANDARD_MASTER_BOOTSTRAP_MULTIPLIER})
+ * @param pendingSetupMigration  True when deprecated testnet setup detected
+ * @param targetServices   How many services the fleet is aiming for
+ */
+export declare function computeRequiredMasterEth({ services, minEoaGasEth, standardMultiplier, pendingSetupMigration, targetServices, }: {
+    services: Array<{
+        service_id: number | null | undefined;
+        step?: string;
+    }>;
+    minEoaGasEth: bigint;
+    standardMultiplier?: bigint;
+    pendingSetupMigration?: boolean;
+    targetServices?: number;
+}): 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
+ *  all agree on a single "one-shot fund the operator" number.
+ *
+ *  Components for a 1-service standard-mode bootstrap:
+ *    - STAGE1_AGENT_ETH (0.010 ETH): master → HD-1 fleet-agent transfer.
+ *      HD-1 pays for its own Safe deploy + register + setAgentWallet out
+ *      of this; leftover covers service 1's Stage 2 work (mech deploy +
+ *      rebind). May get a conditional minEoaGasEth top-up from master if
+ *      Stage 1's gas eats too much of the original transfer.
+ *    - minEoaGasEth × STANDARD_MASTER_BOOTSTRAP_MULTIPLIER (0.010 ETH):
+ *      master gas budget across both stages. Real spend (~0.0025 ETH at
+ *      typical 6 gwei Base Sepolia) leaves room for ~4× gas-spike margin
+ *      plus the conditional HD-1 top-up.
+ *    - minEoaGasEth × (targetServices - 1): per-extra-service top-up for
+ *      services 2..N. Service 1 piggybacks on HD-1's Stage 1 funding.
+ *
+ *  Total for N=1: 0.010 + 0.010 = 0.020 ETH.
+ *  Total for N=2: 0.025 ETH.
+ *  Total for N=3: 0.030 ETH.
+ *
+ *  This number works ONLY when Stage 2's internal gate is `minEoaGasEth ×
+ *  1n` (0.005 ETH) — not the historic `× 2n`. After Stage 1 transfers 0.010
+ *  out, master sits at ~0.0099 ETH (0.020 minus transfer minus Stage 1
+ *  funding-tx gas). The 0.005 gate clears that with margin; the 0.010 gate
+ *  did not. See the Stage 2 gate at ensureStage1And2 line ~484.
+ *
+ *  Operator may see a "low runway" warning after bootstrap — that's
+ *  intentional. The operator-facing 0.020 ETH covers bootstrap completion,
+ *  not multi-week post-bootstrap runway. Top-up is a separate concern.
+ */
+export declare const STAGE1_AGENT_ETH = 10000000000000000n;
+export declare function stage1MinMasterEth(config: {
+    minEoaGasEth: bigint;
+}, targetServices?: number): bigint;
 export interface FleetBootstrapperOptions {
     earningDir?: string;
     chain?: 'base' | 'base-sepolia';
@@ -45,6 +119,16 @@ export interface FleetBootstrapperOptions {
      * testnet funding an explicit operator action.
      */
     autoTestnetFaucet?: boolean;
+    /**
+     * Max in-process attempts for the ERC-8004 Safe-binding step (jinn-mono-h74p).
+     * Defaults to 3. Tests pass small values to keep retry budgets predictable.
+     */
+    safeBindingMaxAttempts?: number;
+    /**
+     * Delay between Safe-binding retries (jinn-mono-h74p). Defaults to 3000 ms
+     * (~1.5 Base Sepolia blocks). Tests pass 0 to skip the sleep entirely.
+     */
+    safeBindingRetryDelayMs?: number;
 }
 export declare class FleetBootstrapper {
     private readonly store;
@@ -60,8 +144,38 @@ export declare class FleetBootstrapper {
     private readonly faucetLoopTimeoutMs;
     private readonly now;
     private readonly autoTestnetFaucet;
+    private readonly safeBindingMaxAttempts;
+    private readonly safeBindingRetryDelayMs;
     constructor(options?: FleetBootstrapperOptions);
     getStatus(): Promise<FleetState>;
+    /**
+     * Run `bindAgentWalletToSafe` with the freshly-deployed-Safe race retry
+     * (jinn-mono-h74p, corrected in jinn-mono-k1ng).
+     *
+     * The race: against a fresh 1/1 Safe on Base Sepolia, the first
+     * setAgentWallet attempt reverts with "Execution reverted for an unknown
+     * reason"; the same Safe + same agentId a few seconds later succeeds.
+     *
+     * The h74p version of the retry only wrapped the call in a try/catch.
+     * In production, `bindAgentWalletToSafe` doesn't throw on revert — it
+     * returns a `{ ok: false, error }` outcome — so the catch never fired
+     * and the retry was dead code. The per-service path "worked" anyway
+     * because it persists `safe_binding_pending` and the next bootstrap
+     * resumes the bind. Stage 1 had no equivalent safety net, so a single
+     * `ok: false` halted bootstrap (the 2026-05-18 canary failure).
+     *
+     * This wrapper:
+     *   - Retries on returned `ok: false` (the way the race actually
+     *     manifests in production).
+     *   - Also retries on thrown exceptions (defense-in-depth in case viem
+     *     error handling changes).
+     *   - Returns the final outcome; callers decide whether to throw, mark
+     *     pending, or proceed.
+     *
+     * Single attempt budget: `safeBindingMaxAttempts` × `safeBindingRetryDelayMs`
+     * (defaults: 3 × 3 s = ~9 s).
+     */
+    private bindAgentWalletWithRetry;
     /**
      * Conservative daily master gas (wei): max(DEFAULT, rough tx count from poll interval × cost).
      */
@@ -83,6 +197,43 @@ export declare class FleetBootstrapper {
      * IdentityCard's "binding pending" chip on Overview.
      */
     retryAgentBindingFor(serviceIndex: number, password: string): Promise<FleetState>;
+    /**
+     * Stage 1 — Identity (universal). Walks: wallet → predict Safe (from
+     * HD-index-1 agent EOA) → ETH funding gate → deploy Safe → mint agentId
+     * + setAgentWallet via ERC-1271. Idempotent and re-entrant. Does NOT
+     * touch service rows or staking — those belong to Stage 2.
+     *
+     * Fleet-level fields written:
+     *   - fleet_safe_address (after predict)
+     *   - fleet_agent_id, fleet_identity_registry, fleet_stage='stage1'
+     *     (after mint + bind)
+     *
+     * Funding gate: requires ETH on the master EOA only (no OLAS). On testnet,
+     * the existing CDP faucet loop drains as usual when `autoTestnetFaucet`
+     * is enabled.
+     *
+     * See docs/superpowers/specs/2026-05-13-plug-in-builder-entry-point-design.md §5.1.
+     */
+    ensureStage1(password: string): Promise<FleetBootstrapResult>;
+    /**
+     * Stage 1 + Stage 2 — full operator bootstrap. Calls `ensureStage1`
+     * first; on success, walks Stage 2 per service. Builder-only users who
+     * have completed Stage 1 and call this method later begin Stage 2 from
+     * `awaiting_stake` for the first service row (created lazily here).
+     *
+     * Two-Safe topology in standard mode: `fleet_safe_address !==
+     * services[0].safe_address` because Stage 2's `distributor.stake()`
+     * creates its own Safe. In self-bond mode the two converge (both
+     * derived from HD-index-1).
+     *
+     * See docs/superpowers/specs/2026-05-13-plug-in-builder-entry-point-design.md §5.1.
+     */
+    ensureStage1And2(password: string): Promise<FleetBootstrapResult>;
+    /**
+     * Back-compat alias. Existing call sites in `client/src/cli/commands/bootstrap.ts`
+     * and `client/src/cli/commands/fleet-scale.ts` continue to call `bootstrap()`;
+     * forwarding to `ensureStage1And2` preserves their semantics without churn.
+     */
     bootstrap(password: string): Promise<FleetBootstrapResult>;
     /**
      * If the master is only slightly above the minimum, warn about gas runway (heuristic days).
@@ -90,6 +241,12 @@ export declare class FleetBootstrapper {
     private warnMasterEthRunway;
     private ensureMasterWallet;
     private loadExistingMnemonic;
+    /** Deterministic Safe predict from the HD-index-1 agent EOA. */
+    private stepFleetSafePredict;
+    /** Deploy the predicted fleet Safe. Funds the agent EOA from master if needed. */
+    private stepFleetSafeDeploy;
+    /** Mint the fleet agentId + bind Safe via setAgentWallet (ERC-1271). */
+    private stepFleetIdentityRegister;
     private bootstrapService;
     /**
      * Compare persisted per-service state to registry/staking/Safe bytecode and patch store
@@ -167,3 +324,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>;