@jinn-network/client 0.1.5 → 0.1.6-canary.118cd4d0

package/dist/earning/bootstrap.d.ts

@@ -6,6 +6,42 @@
  */
 import type { FleetState, FleetBootstrapResult } from './types.js';
 import { requestTestnetFunding } from './faucet.js';
+/** 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 +81,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 +106,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 +159,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 +203,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