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

package/dist/earning/bootstrap.js

@@ -20,11 +20,95 @@ import { isUnauthorizedAccountError } from '../errors/unauthorized-account.js';
 import { createJinnPublicClient, createJinnWalletClient } from './viem-clients.js';
 import { isTransientEthReadError } from '../chain-read-errors.js';
 import { nextFleetServiceIndex } from './next-service-index.js';
+import { displayFleetServiceIndex } from './fleet-display-index.js';
 import { rpcHostForDisplay } from '../preflight/rpc-network.js';
 import { detectDeprecatedTestnetSetup, migrateDeprecatedTestnetSetup, } from './testnet-setup-migration.js';
 const addr = (value) => getAddress(value);
 const SAFE_TOKEN_BOOTSTRAP_MULTIPLIER = 2n;
-const STANDARD_MASTER_BOOTSTRAP_MULTIPLIER = 2n;
+/**
+ * 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 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 const SELF_BOND_ETH_PER_SERVICE = 30000000000000000n; // 0.03 ETH
+/**
+ * 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 function computeRequiredMasterEth({ services, minEoaGasEth, pendingSetupMigration = false, targetServices = 1, stakingMode = 'standard', preStage1 = false, }) {
+    if (stakingMode !== 'standard') {
+        return SELF_BOND_ETH_PER_SERVICE * BigInt(targetServices);
+    }
+    // Reconciled `standardFleetAlreadyComplete` — a single definition replacing
+    // the three historic inline variants. Adopts the strictest of them (the
+    // FleetBootstrapper variant): the fleet must have at least `targetServices`
+    // rows AND every row must be operational AND no deprecated-setup migration
+    // may be pending. A migration-wiped fleet (which sets
+    // `pendingSetupMigration`) is therefore never short-circuited to `0n`.
+    const standardFleetAlreadyComplete = services.length >= targetServices &&
+        services.every(s => s.step !== undefined && isOperationalServiceStep(s.step)) &&
+        !pendingSetupMigration;
+    if (standardFleetAlreadyComplete)
+        return 0n;
+    if (preStage1) {
+        // Stage 1 gate: master → agent transfer (STAGE1_AGENT_ETH) + the master's
+        // own gas reserve, plus per-extra-service transfers. See jinn-mono-u34i.
+        return stage1MinMasterEth({ minEoaGasEth }, targetServices);
+    }
+    // Stage 2 master gas budget — covers distributor.stake() (~0.003 ETH at
+    // typical 6 gwei Base Sepolia) plus per-extra-service top-up transfers.
+    // Service 1 piggybacks on HD-1's Stage 1 funding, so the base term is a
+    // single `minEoaGasEth` (not `× 2`). See jinn-mono-u34i.
+    return minEoaGasEth + minEoaGasEth * BigInt(Math.max(0, targetServices - 1));
+}
 /** 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
@@ -64,8 +148,17 @@ export function stage1MinMasterEth(config, targetServices = 1) {
         config.minEoaGasEth * STANDARD_MASTER_BOOTSTRAP_MULTIPLIER +
         extraServiceTransfers);
 }
-/** Conservative default: ~0.001 ETH/day master gas if not configured. */
-const DEFAULT_MASTER_ETH_DAILY_WEI = 1000000000000000n;
+/**
+ * Conservative default: ~0.0005 ETH/day master gas if not configured.
+ *
+ * Post-bootstrap master burn is dominated by rare BalanceTopupLoop top-ups,
+ * not every-poll activity — the previous 0.001 ETH/day floor (alongside a
+ * poll-based blend, since removed) over-estimated steady-state burn and
+ * surfaced a misleading "1 days runway" dashboard reading at ~0.008 ETH
+ * balances (#288). Mirrored at client/src/api/status-build.ts; collapsing
+ * the two copies is a deferred follow-up per the #288 design note.
+ */
+const DEFAULT_MASTER_ETH_DAILY_WEI = 500000000000000n;
 /** Warn when ETH above the minimum would last fewer than this many days at the daily estimate. */
 const MASTER_ETH_RUNWAY_WARN_DAYS = 7n;
 /**
@@ -210,16 +303,14 @@ export class FleetBootstrapper {
             : new Error(String(lastThrowError));
     }
     /**
-     * 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.
      */
-    estimateMasterDailyGasWei(pollIntervalMs) {
-        const interval = Math.max(pollIntervalMs ?? 5000, 1000);
-        const pollsPerDay = 86400000 / interval;
-        // Assume at most one funding-sized tx per ~600 polls (~50 min at 5s), capped at 12/day
-        const txsPerDay = Math.min(Math.ceil(pollsPerDay / 600), 12);
-        const txCostWei = 150000n * 2000000000n; // ~150k gas @ 2 gwei
-        const fromPoll = BigInt(txsPerDay) * txCostWei;
-        return fromPoll > DEFAULT_MASTER_ETH_DAILY_WEI ? fromPoll : DEFAULT_MASTER_ETH_DAILY_WEI;
+    estimateMasterDailyGasWei(_pollIntervalMs) {
+        return DEFAULT_MASTER_ETH_DAILY_WEI;
     }
     /**
      * Snapshot of the current persisted fleet state. Reads only — no chain
@@ -389,12 +480,8 @@ export class FleetBootstrapper {
             // Phase 1b: Check master funding for the full operator path.
             const masterAddress = state.master_address;
             let masterBalance = await this.publicClient.getBalance({ address: masterAddress });
-            // Self-bond mode needs much more ETH 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.
-            // On re-runs, include ETH already held by funded agents/safes in the total.
-            const SELF_BOND_ETH_PER_SERVICE = 30000000000000000n; // 0.03 ETH
+            // On re-runs, include ETH already held by funded agents/safes in the
+            // total for self-bond mode.
             let systemEth = masterBalance;
             if (this.stakingMode === 'self-bond') {
                 for (const svc of state.services) {
@@ -416,26 +503,20 @@ export class FleetBootstrapper {
                 stakingMode: this.stakingMode,
                 currentStakingContract: this.config.stakingContract,
             }).services.length > 0;
-            const completedCountBeforeFunding = state.services.filter(s => isOperationalServiceStep(s.step)).length;
-            const standardFleetAlreadyComplete = this.stakingMode === 'standard' &&
-                !pendingSetupMigration &&
-                completedCountBeforeFunding >= this.targetServices;
-            const standardFleetHasInProgressServices = this.stakingMode === 'standard' && state.services.length > 0;
-            const requiredMasterEth = this.stakingMode === 'standard'
-                ? (standardFleetAlreadyComplete
-                    ? 0n
-                    // Stage 2 master gas budget — covers distributor.stake() (~0.003
-                    // ETH at typical 6 gwei Base Sepolia) plus per-extra-service
-                    // top-up transfers. Previously this was `× 2` for fresh fleets,
-                    // which double-counted a service-1 transfer that doesn't actually
-                    // fire (HD-1 carries Stage 1 leftover, gets a conditional top-up
-                    // only if needed). See jinn-mono-u34i: the `× 2` figure also
-                    // exceeded the post-Stage-1 master balance at the operator-facing
-                    // 0.020 ETH budget by ~127k gwei of Stage 1 gas burn, causing a
-                    // second funding prompt.
-                    : this.config.minEoaGasEth +
-                        this.config.minEoaGasEth * BigInt(Math.max(0, this.targetServices - 1)))
-                : SELF_BOND_ETH_PER_SERVICE * BigInt(this.targetServices);
+            // Single source of truth: the master-ETH gate is computed by
+            // `computeRequiredMasterEth` (defined above), the same helper the
+            // read-only `planFleetFunding` view routes through. Re-deriving it inline
+            // here is the u34i cross-module invariant-drift hazard. `ensureStage1And2`
+            // only reaches this point AFTER `ensureStage1` has succeeded, so the
+            // fleet is always past Stage 1 — `preStage1` is `false`.
+            const requiredMasterEth = computeRequiredMasterEth({
+                services: state.services,
+                minEoaGasEth: this.config.minEoaGasEth,
+                pendingSetupMigration,
+                targetServices: this.targetServices,
+                stakingMode: this.stakingMode,
+                preStage1: false,
+            });
             const autoFaucetEnabled = this.autoTestnetFaucet;
             // Re-sum system ETH (master + agent/safe balances for self-bond mode).
             // Hoisted so the drip loop below can refresh cheaply.
@@ -578,7 +659,7 @@ export class FleetBootstrapper {
             };
         }
         catch (error) {
-            const { summary, hint, rawMessage } = formatBootstrapOperatorMessage(error);
+            const { summary, hint, rawMessage, category } = formatBootstrapOperatorMessage(error);
             const userMessage = hint !== undefined ? `${summary}\nHint: ${hint}` : summary;
             if (this.debug) {
                 console.error(`[fleet-bootstrap] Bootstrap failed:`, error);
@@ -594,11 +675,21 @@ export class FleetBootstrapper {
                     console.error(`[fleet-bootstrap] raw: ${rawMessage.split('\n')[0]}`);
                 }
             }
+            // Extract a tx hash embedded in the error message by the on-chain revert
+            // paths (format: "...tx failed for service N: 0x<hash>" or
+            // "...tx reverted: 0x<hash>"). Surfaced in the fatal envelope so the SPA
+            // can render a block-explorer link. jinn-mono-hjex reviewer fix.
+            const txHashMatch = /(0x[a-fA-F0-9]{64})/.exec(rawMessage);
+            const txHash = txHashMatch ? txHashMatch[1] : null;
             return {
                 ok: false,
                 fleet_state: state,
                 message: userMessage,
                 rawErrorMessage: rawMessage,
+                // Preserve the structured category so the error envelope in main.ts
+                // can surface it in `details.category` for SPA consumers. jinn-mono-hjex.6
+                ...(category !== undefined ? { errorCategory: category } : {}),
+                ...(txHash !== null ? { txHash } : {}),
             };
         }
     }
@@ -1044,6 +1135,39 @@ export class FleetBootstrapper {
                 return this.store.updateService(index, { step: 'staked' });
             }
         }
+        // Pre-stake precondition: if migration cleared service_id but kept agent_address,
+        // check the EOA is not already registered on-chain as an agent instance. If it is,
+        // calling stake() again would revert with AgentInstanceRegistered (selector 0x631695bd)
+        // and there is nothing useful the operator can do without rotating the agent EOA.
+        // Fail fast with a typed error instead of letting the contract revert.
+        //
+        // ServiceRegistryL2 exposes the `mapAgentInstanceOperators(address) → address` mapping:
+        // it returns the operator address that registered the given agent instance, or the
+        // zero address when no operator has bound that instance. A non-zero return means the
+        // EOA is already bound. (There is no `mapAgentInstances(address) → uint256` getter on
+        // the deployed registry — an earlier draft of this guard referenced one and was a
+        // permanent no-op.)
+        if (svc.agent_address && svc.service_id === null && this.config.serviceRegistry) {
+            let alreadyBound = false;
+            try {
+                const boundOperator = (await this.publicClient.readContract({
+                    address: getAddress(this.config.serviceRegistry),
+                    abi: SERVICE_REGISTRY_L2_ABI,
+                    functionName: 'mapAgentInstanceOperators',
+                    args: [getAddress(svc.agent_address)],
+                }));
+                alreadyBound = boundOperator !== '0x0000000000000000000000000000000000000000';
+            }
+            catch {
+                // Registry read failure is non-fatal — proceed and let stake() surface
+                // the error if the agent really is bound.
+            }
+            if (alreadyBound) {
+                throw new Error(`agent_already_bound: agent EOA ${svc.agent_address} is already registered as an agent instance on-chain. ` +
+                    `The previous setup retirement may have been incomplete. ` +
+                    `Contact support or rotate the agent EOA to continue.`);
+            }
+        }
         // Fresh distributor stake() creates a new on-chain service. If state still
         // references an old Safe (e.g. hand-edited JSON), sweep it before replacing.
         if (svc.service_id === null && svc.safe_address && state.master_address) {
@@ -1109,42 +1233,19 @@ export class FleetBootstrapper {
         const svc = state.services.find(s => s.index === index);
         const serviceId = svc.service_id;
         const stakingAddress = this.stakingAddressForService(svc);
-        // `reStake()` is operator-scoped: the master EOA must match the
-        // distributor's recorded `mapServiceIdCuratingAgents[serviceId]` entry.
-        // If it doesn't, the operator is likely using the wrong earning dir or
-        // password, or the service needs owner / managing-agent recovery.
-        const masterAccount = deriveMasterSigner(mnemonic);
-        const masterWallet = createJinnWalletClient(this.config.rpcUrl, this.chain, masterAccount);
-        const reStakeData = encodeFunctionData({
-            abi: STOLAS_DISTRIBUTOR_ABI,
-            functionName: 'reStake',
-            args: [stakingAddress, BigInt(serviceId)],
+        const di = displayFleetServiceIndex(svc);
+        // Delegate to the standalone exported helper (shared with EvictionLoop /
+        // the dashboard "Re-stake now" CTA). This eliminates the duplicate
+        // implementation (jinn-mono-hjex.3).
+        await recoverEvictedService({
+            serviceDisplayIndex: di,
+            serviceId,
+            stakingAddress: stakingAddress,
+            distributorAddress: this.config.distributorAddress,
+            rpcUrl: this.config.rpcUrl,
+            chain: this.chain,
+            mnemonic,
         });
-        console.error(`[fleet-bootstrap] Service ${index}: calling distributor.reStake() for evicted service ${serviceId}`);
-        let reStakeHash;
-        try {
-            reStakeHash = await viemSendTransactionWithRetry(masterWallet, this.publicClient, {
-                account: masterAccount,
-                to: addr(this.config.distributorAddress),
-                data: reStakeData,
-                gas: 1500000n,
-            });
-        }
-        catch (err) {
-            const message = flattenErrorMessage(err);
-            if (isUnauthorizedAccountError(message)) {
-                throw new Error(`Service ${index} (service_id ${serviceId}) is evicted on the staking proxy, but master EOA ${masterAccount.address} is not authorized to reStake it. ` +
-                    `The distributor only permits the recorded service operator, a managing agent, or the owner. ` +
-                    `Verify JINN_EARNING_DIR and JINN_PASSWORD derive the original master EOA for this service, then re-run jinn bootstrap; otherwise request owner / managing-agent recovery or abandon-and-rebootstrap. ` +
-                    `reStake revert: ${message}`);
-            }
-            throw err;
-        }
-        const receipt = await waitForTransactionReceiptWithRetry(this.publicClient, reStakeHash);
-        if (receipt.status !== 'success') {
-            throw new Error(`reStake failed for service ${index}: ${reStakeHash}`);
-        }
-        console.error(`[fleet-bootstrap] Service ${index}: reStake confirmed (tx: ${reStakeHash})`);
         // Service is now Staked again with the same service_id, safe_address, and mech_address.
         // Step back to `mech_deployed` so the resume loop advances through
         // `stepRegisterAgent` (idempotent — short-circuits if `agent_id` is
@@ -1897,4 +1998,50 @@ export class FleetBootstrapper {
 }
 /** @deprecated Use FleetBootstrapper */
 export const EarningBootstrapper = FleetBootstrapper;
+/**
+ * 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 async function recoverEvictedService(opts) {
+    const { serviceDisplayIndex, serviceId, stakingAddress, distributorAddress, rpcUrl, chain, mnemonic, } = opts;
+    const masterAccount = deriveMasterSigner(mnemonic);
+    const publicClient = createJinnPublicClient(rpcUrl, chain);
+    const masterWallet = createJinnWalletClient(rpcUrl, chain, masterAccount);
+    const reStakeData = encodeFunctionData({
+        abi: STOLAS_DISTRIBUTOR_ABI,
+        functionName: 'reStake',
+        args: [addr(stakingAddress), BigInt(serviceId)],
+    });
+    console.error(`[eviction-recovery] Service ${serviceDisplayIndex}: calling distributor.reStake() for evicted service ${serviceId}`);
+    let reStakeHash;
+    try {
+        reStakeHash = await viemSendTransactionWithRetry(masterWallet, publicClient, {
+            account: masterAccount,
+            to: addr(distributorAddress),
+            data: reStakeData,
+            gas: 1500000n,
+        });
+    }
+    catch (err) {
+        const message = flattenErrorMessage(err);
+        if (isUnauthorizedAccountError(message)) {
+            throw new Error(`Service ${serviceDisplayIndex} (service_id ${serviceId}) is evicted on the staking proxy, but master EOA ` +
+                `${masterAccount.address} is not authorized to reStake it. ` +
+                `Verify JINN_EARNING_DIR and JINN_PASSWORD derive the original master EOA for this service. ` +
+                `reStake revert: ${message}`);
+        }
+        throw err;
+    }
+    const receipt = await waitForTransactionReceiptWithRetry(publicClient, reStakeHash);
+    if (receipt.status !== 'success') {
+        throw new Error(`reStake failed for service ${serviceDisplayIndex}: ${reStakeHash}`);
+    }
+    console.error(`[eviction-recovery] Service ${serviceDisplayIndex}: reStake confirmed (tx: ${reStakeHash})`);
+}
 //# sourceMappingURL=bootstrap.js.map