@jinn-network/client 0.1.2 → 0.1.3-canary.262e5cda

package/dist/earning/bootstrap.js

@@ -5,11 +5,12 @@
  * Phase 2 (per-service): derive agent → stake → deploy mech
  */
 import { decodeEventLog, encodeAbiParameters, encodeFunctionData, formatEther, getAddress, zeroAddress, } from 'viem';
-import { ERC20_ABI, EVENT_TOPICS, SERVICE_MANAGER_ABI, SERVICE_REGISTRY_APPROVE_ABI, SERVICE_REGISTRY_L2_ABI, STAKING_ABI, MECH_MARKETPLACE_CREATE_ABI, STOLAS_DISTRIBUTOR_ABI, STOLAS_STAKING_SLOTS_ABI, cidToBytes32, getChainConfig, } from './contracts.js';
+import { ERC20_ABI, EVENT_TOPICS, IDENTITY_REGISTRY_ABI, IDENTITY_REGISTRY_ADDRESSES, SERVICE_MANAGER_ABI, SERVICE_REGISTRY_APPROVE_ABI, SERVICE_REGISTRY_L2_ABI, STAKING_ABI, MECH_MARKETPLACE_CREATE_ABI, STOLAS_DISTRIBUTOR_ABI, STOLAS_STAKING_SLOTS_ABI, applyChainGasOverrides, cidToBytes32, getChainConfig, } from './contracts.js';
 import { executeSafeTxBatch, executeSafeTxDirect, initDeployedSafe, initPredictedSafe, } from './safe-adapter.js';
+import { bindAgentWalletToSafe } from './agent-wallet-binding.js';
 import { FleetStateStore } from './store.js';
 import { generateMnemonic, encryptMnemonic, decryptMnemonic, deriveMasterAddress, deriveMasterSigner, deriveAgentAddress, deriveAgentSigner, walletPrivateKeyAtIndex, } from './wallet.js';
-import { createDefaultServiceState } from './types.js';
+import { createDefaultServiceState, isOperationalServiceStep } from './types.js';
 import { formatBootstrapOperatorMessage, isJinnDebug, } from '../operator-errors.js';
 import { reconcileServiceAgainstChain, } from './reconcile.js';
 import { previousSafeBeingAbandoned, sweepOrphanedServiceFunds, } from './orphan-sweep.js';
@@ -20,8 +21,10 @@ import { createJinnPublicClient, createJinnWalletClient } from './viem-clients.j
 import { isTransientEthReadError } from '../chain-read-errors.js';
 import { nextFleetServiceIndex } from './next-service-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;
 /** Conservative default: ~0.001 ETH/day master gas if not configured. */
 const DEFAULT_MASTER_ETH_DAILY_WEI = 1000000000000000n;
 /** Warn when ETH above the minimum would last fewer than this many days at the daily estimate. */
@@ -36,6 +39,8 @@ export class FleetBootstrapper {
     debug;
     masterEthDailyEstimateWei;
     env;
+    requestFunding;
+    autoTestnetFaucet;
     constructor(options = {}) {
         this.store = new FleetStateStore(options.earningDir);
         this.chain = options.chain ?? 'base';
@@ -43,17 +48,23 @@ export class FleetBootstrapper {
         this.stakingMode = options.stakingMode ?? 'standard';
         this.targetServices = options.targetServices ?? 1;
         this.debug = options.debug ?? isJinnDebug();
+        this.requestFunding = options.requestFunding ?? requestTestnetFunding;
+        this.autoTestnetFaucet =
+            options.autoTestnetFaucet ?? this.env['JINN_DISABLE_TESTNET_FAUCET'] !== '1';
         const dailyOpt = options.masterEthDailyEstimateWei;
         this.masterEthDailyEstimateWei =
             dailyOpt !== undefined
                 ? BigInt(dailyOpt)
                 : this.estimateMasterDailyGasWei(options.pollIntervalMs);
-        this.config = getChainConfig(this.chain, {
+        this.config = applyChainGasOverrides(getChainConfig(this.chain, {
             testnetL2DeploymentPath: options.testnetL2DeploymentPath,
             testnetL2TokenDeploymentPath: options.testnetL2TokenDeploymentPath,
             testnetMechDeploymentPath: options.testnetMechDeploymentPath,
             testnetStolasDeploymentPath: options.testnetStolasDeploymentPath,
             testnetClaimRegistryDeploymentPath: options.testnetClaimRegistryDeploymentPath,
+        }), {
+            minEoaGasWei: options.minEoaGasWei ?? this.env['JINN_MIN_EOA_GAS_WEI'],
+            minSafeEthWei: options.minSafeEthWei ?? this.env['JINN_MIN_SAFE_ETH_WEI'],
         });
         if (options.rpcUrl) {
             this.config.rpcUrl = options.rpcUrl;
@@ -108,10 +119,23 @@ export class FleetBootstrapper {
                     }
                 }
             }
+            const pendingSetupMigration = detectDeprecatedTestnetSetup({
+                state,
+                chain: this.chain,
+                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'
-                ? this.config.minEoaGasEth
+                ? (standardFleetAlreadyComplete
+                    ? 0n
+                    : this.config.minEoaGasEth * (standardFleetHasInProgressServices ? 1n : STANDARD_MASTER_BOOTSTRAP_MULTIPLIER))
                 : SELF_BOND_ETH_PER_SERVICE * BigInt(this.targetServices);
-            const autoFaucetEnabled = this.env['JINN_DISABLE_TESTNET_FAUCET'] !== '1';
+            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.
             const refreshSystemEth = async () => {
@@ -145,7 +169,7 @@ export class FleetBootstrapper {
                     `Draining CDP faucet on ${this.chain} via ${rpcHostForDisplay(this.config.rpcUrl)} ` +
                     `(each drip ≈ 0.0001 ETH, up to ${MAX_FAUCET_ITERS} drips; expect ~30-60 s on first run).`);
                 for (let i = 0; i < MAX_FAUCET_ITERS; i++) {
-                    const faucetResult = await requestTestnetFunding(masterAddress, 'base-sepolia');
+                    const faucetResult = await this.requestFunding(masterAddress, 'base-sepolia');
                     if (!faucetResult.ok) {
                         if (faucetResult.rateLimited) {
                             console.error(`[fleet-bootstrap] CDP faucet rate-limited after ${i} drips: ${faucetResult.reason}`);
@@ -191,19 +215,37 @@ export class FleetBootstrapper {
             this.warnMasterEthRunway(masterAddress, masterBalance, requiredMasterEth);
             // Phase 2: Bootstrap services up to target
             const mnemonic = await decryptMnemonic(await this.store.loadMnemonicKeystore(), password);
+            if (pendingSetupMigration) {
+                const masterAccount = deriveMasterSigner(mnemonic);
+                const masterWallet = createJinnWalletClient(this.config.rpcUrl, this.chain, masterAccount);
+                const migration = await migrateDeprecatedTestnetSetup({
+                    stateStore: this.store,
+                    state,
+                    chain: this.chain,
+                    stakingMode: this.stakingMode,
+                    currentStakingContract: this.config.stakingContract,
+                    distributorAddress: this.config.distributorAddress,
+                    publicClient: this.publicClient,
+                    masterWallet,
+                });
+                state = migration.state;
+            }
             state = await this.reconcileFleetWithChain(state, mnemonic);
             // Resume all services. For incomplete services, this picks up where they
             // left off. For "complete" services in standard mode, this also runs the
             // eviction recovery check (since on-chain state may have changed since
             // the daemon was last running — e.g., evicted due to inactivity).
             for (const svc of state.services) {
-                if (svc.step !== 'complete') {
+                if (!isOperationalServiceStep(svc.step)) {
                     console.error(`[fleet-bootstrap] Resuming service ${svc.index} at step '${svc.step}'`);
                 }
+                else if (svc.step === 'safe_binding_pending') {
+                    console.error(`[fleet-bootstrap] Resuming service ${svc.index} at step 'safe_binding_pending'`);
+                }
                 state = await this.resumeService(state, mnemonic, svc.index);
             }
             // Then create new services if needed
-            const completedCount = state.services.filter(s => s.step === 'complete').length;
+            const completedCount = state.services.filter(s => isOperationalServiceStep(s.step)).length;
             const needed = this.targetServices - completedCount;
             if (needed > 0) {
                 console.error(`[fleet-bootstrap] ${completedCount}/${this.targetServices} services complete, bootstrapping ${needed} more`);
@@ -215,7 +257,7 @@ export class FleetBootstrapper {
             return {
                 ok: true,
                 fleet_state: state,
-                message: `Fleet bootstrap complete. ${state.services.filter(s => s.step === 'complete').length}/${this.targetServices} services running.`,
+                message: `Fleet bootstrap complete. ${state.services.filter(s => isOperationalServiceStep(s.step)).length}/${this.targetServices} services running.`,
             };
         }
         catch (error) {
@@ -292,10 +334,13 @@ export class FleetBootstrapper {
      * when local JSON is ahead, behind, or stale (idempotent; safe to repeat).
      */
     async reconcileFleetWithChain(state, mnemonic) {
-        const ctx = { stakingContract: this.config.stakingContract };
         let next = state;
         for (const svc of state.services) {
             const signals = await this.gatherChainSignals(svc);
+            const ctx = {
+                stakingContract: this.stakingAddressForService(svc),
+                preserveExistingSetup: this.shouldPreserveExistingSetup(svc),
+            };
             const result = reconcileServiceAgainstChain(this.stakingMode, svc, signals, ctx);
             if (result) {
                 const abandoned = previousSafeBeingAbandoned(svc, result.patch);
@@ -348,7 +393,7 @@ export class FleetBootstrapper {
             };
         }
         const id = svc.service_id;
-        const stakingAddr = this.config.stakingContract;
+        const stakingAddr = this.stakingAddressForService(svc);
         const registryAddr = this.config.serviceRegistry;
         let stakingState = 0;
         try {
@@ -412,21 +457,45 @@ export class FleetBootstrapper {
         let svc = state.services.find(s => s.index === index);
         if (!svc)
             throw new Error(`Service ${index} not found in state`);
+        if (this.stakingMode === 'standard' &&
+            svc.error &&
+            this.shouldPreserveExistingSetup(svc)) {
+            return state;
+        }
         // Eviction recovery: even for "complete" services, check if on-chain shows
         // evicted (state=2). If so, unstake and reset to awaiting_stake so the
         // bootstrap restakes fresh. Only applies to standard mode (distributor-managed).
         if (this.stakingMode === 'standard' &&
             svc.service_id !== null &&
-            (svc.step === 'complete' || svc.step === 'mech_deployed' || svc.step === 'staked')) {
-            const onChainState = await this.getStakingState(svc.service_id);
+            (isOperationalServiceStep(svc.step) || svc.step === 'mech_deployed' || svc.step === 'staked')) {
+            let onChainState;
+            try {
+                onChainState = await this.getStakingState(svc.service_id, svc.staking_address);
+            }
+            catch (error) {
+                if (this.shouldPreserveExistingSetup(svc)) {
+                    console.error(`[jinn-earning] Service ${index}: existing setup staking state could not be checked automatically. Leaving local service id and wallet fields unchanged for recovery/support.`);
+                    return state;
+                }
+                throw error;
+            }
             if (onChainState === 2) {
                 console.error(`[jinn-earning] Noticed service ${svc.service_id} (fleet index ${index}) evicted on-chain; running distributor reStake to restake.`);
                 state = await this.recoverEvictedService(state, mnemonic, index);
                 svc = state.services.find(s => s.index === index);
             }
         }
-        if (svc.step === 'complete')
+        if (isOperationalServiceStep(svc.step)) {
+            // Identity binding retry: services at `safe_binding_pending` are already
+            // staked and operational, but their ERC-8004 Safe→agentId link still
+            // needs to be written. Older `complete` services with safe_bound=false
+            // are treated the same way so legacy operators self-heal on resume.
+            if (svc.agent_id && svc.safe_address && svc.safe_bound_to_agent !== true) {
+                console.error(`[fleet-bootstrap] Service ${index}: agent_id=${svc.agent_id} with unbound Safe; running binding step.`);
+                state = await this.stepRegisterAgent(state, mnemonic, index);
+            }
             return state;
+        }
         if (this.stakingMode === 'standard') {
             return this.resumeServiceStandard(state, mnemonic, index);
         }
@@ -438,11 +507,18 @@ export class FleetBootstrapper {
             state = await this.stepStolasStake(state, mnemonic, index);
         }
         // Reload service state after stake
-        const updatedSvc = (await this.store.load(this.chain)).services.find(s => s.index === index);
+        let updatedSvc = (await this.store.load(this.chain)).services.find(s => s.index === index);
         if (!updatedSvc)
             throw new Error(`Service ${index} disappeared from state`);
         if (updatedSvc.step === 'staked' || updatedSvc.step === 'mech_deployed') {
             state = await this.stepDeployMech(state, mnemonic, index);
+            updatedSvc = (await this.store.load(this.chain)).services.find(s => s.index === index);
+        }
+        if (updatedSvc.step === 'mech_deployed' ||
+            updatedSvc.step === 'agent_registered' ||
+            updatedSvc.step === 'safe_binding_pending') {
+            state = await this.stepRegisterAgent(state, mnemonic, index);
+            updatedSvc = (await this.store.load(this.chain)).services.find(s => s.index === index);
         }
         return this.store.load(this.chain);
     }
@@ -474,6 +550,11 @@ export class FleetBootstrapper {
         }
         if (svc.step === 'staked' || svc.step === 'mech_deployed') {
             state = await this.stepDeployMech(state, mnemonic, index);
+            svc = (await this.store.load(this.chain)).services.find(s => s.index === index);
+        }
+        if (svc.step === 'mech_deployed' || svc.step === 'agent_registered' || svc.step === 'safe_binding_pending') {
+            state = await this.stepRegisterAgent(state, mnemonic, index);
+            svc = (await this.store.load(this.chain)).services.find(s => s.index === index);
         }
         return this.store.load(this.chain);
     }
@@ -481,7 +562,7 @@ export class FleetBootstrapper {
         const svc = state.services.find(s => s.index === index);
         // Idempotency: if this service already has an id and is already staked, skip
         if (svc.service_id !== null) {
-            const stakingState = await this.getStakingState(svc.service_id);
+            const stakingState = await this.getStakingState(svc.service_id, svc.staking_address);
             if (stakingState === 1) {
                 console.error(`[fleet-bootstrap] Service ${index} already staked, skipping`);
                 return this.store.updateService(index, { step: 'staked' });
@@ -551,17 +632,17 @@ export class FleetBootstrapper {
         }
         const svc = state.services.find(s => s.index === index);
         const serviceId = svc.service_id;
-        // `distributor.stake()` writes only to guard-scoped curating-agent maps,
-        // never to the top-level `mapCuratingAgents` that `reStake()` reads —
-        // so plain operators will hit `UnauthorizedAccount` here unless the
-        // distributor owner pre-whitelisted them. Catch-and-surface below rather
-        // than retry forever.
+        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: [this.config.stakingContract, BigInt(serviceId)],
+            args: [stakingAddress, BigInt(serviceId)],
         });
         console.error(`[fleet-bootstrap] Service ${index}: calling distributor.reStake() for evicted service ${serviceId}`);
         let reStakeHash;
@@ -576,10 +657,9 @@ export class FleetBootstrapper {
         catch (err) {
             const message = flattenErrorMessage(err);
             if (isUnauthorizedAccountError(message)) {
-                throw new Error(`Service ${index} (service_id ${serviceId}) is evicted on the staking proxy and reStake is gated by the distributor's curating-agent whitelist. ` +
-                    `Master EOA ${masterAccount.address} is not authorized. To recover: ` +
-                    `(a) have the distributor owner call setCuratingAgents([${masterAccount.address}], [true]) on ${this.config.distributorAddress}, then re-run jinn bootstrap; or ` +
-                    `(b) abandon this service and provision a new one (stOLAS bond stays with the old Safe until it's manually swept). ` +
+                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;
@@ -590,16 +670,19 @@ export class FleetBootstrapper {
         }
         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.
-        // Mark the step as complete so the bootstrap doesn't try to re-stake or re-deploy mech.
+        // Step back to `mech_deployed` so the resume loop advances through
+        // `stepRegisterAgent` (idempotent — short-circuits if `agent_id` is
+        // already set; mints if a pre-j07 operator was just re-staked and
+        // never had the operator agent NFT). See jinn-mono-jgp.
         return this.store.updateService(index, {
-            step: 'complete',
+            step: 'mech_deployed',
         });
     }
     async stepDeployMech(state, mnemonic, index) {
         const svc = state.services.find(s => s.index === index);
         if (svc.mech_address) {
             console.error(`[fleet-bootstrap] Service ${index}: mech already deployed at ${svc.mech_address}`);
-            return this.store.updateService(index, { step: 'complete' });
+            return this.store.updateService(index, { step: 'mech_deployed' });
         }
         const serviceId = svc.service_id;
         const safeAddress = svc.safe_address;
@@ -658,9 +741,173 @@ export class FleetBootstrapper {
         console.error(`[fleet-bootstrap] Service ${index}: mech deployed at ${mechAddress}`);
         return this.store.updateService(index, {
             mech_address: mechAddress,
-            step: 'complete',
+            step: 'mech_deployed',
         });
     }
+    /**
+     * ERC-8004 IdentityRegistry mint + Safe wallet bind (jinn-mono-j07,
+     * jinn-mono-aev).
+     *
+     * Two on-chain effects, gated independently for idempotency:
+     *
+     * 1. **Mint** (jinn-mono-j07): one operator agent NFT per service Safe;
+     *    the agent EOA owns the token. Persists `agent_id` (and metadata)
+     *    to state immediately after the receipt parses, so a crash between
+     *    register and the subsequent `setAgentWallet` does not lose the
+     *    token. v0 uses an empty `agentURI` — operators are expected to
+     *    populate it later via `setAgentURI`. Re-run with `svc.agent_id`
+     *    already set short-circuits the mint.
+     *
+     * 2. **Bind** (jinn-mono-aev): `IdentityRegistry.setAgentWallet(agentId,
+     *    safe, deadline, sig)` from the agent EOA. The contract recovers
+     *    `sig` against the Safe via ERC-1271; we wrap the EIP-712
+     *    AgentWalletSet digest in Safe's SafeMessage typed-data and
+     *    raw-ECDSA-sign with the sole owner (= agent EOA). On success,
+     *    `safe_bound_to_agent` flips to true. Re-run with
+     *    `svc.safe_bound_to_agent` already true short-circuits the bind.
+     *    See `agent-wallet-binding.ts` + spec §4.1.
+     *
+     * The bind is a discrete operational state (`safe_binding_pending`) because
+     * the service is already staked and runnable once the mint exists. A failed
+     * binding should be visible and resumable, but should not block the daemon
+     * from reaching the running dashboard.
+     */
+    async stepRegisterAgent(state, mnemonic, index) {
+        void state;
+        let svc = (await this.store.load(this.chain)).services.find(s => s.index === index);
+        if (!svc)
+            throw new Error(`Service ${index} not found in state`);
+        const identityRegistry = this.config.identityRegistry
+            ?? IDENTITY_REGISTRY_ADDRESSES[this.config.chainId];
+        if (!identityRegistry) {
+            throw new Error(`IdentityRegistry address not configured for chainId=${this.config.chainId}; ` +
+                `update IDENTITY_REGISTRY_ADDRESSES in earning/contracts.ts.`);
+        }
+        const agentSigner = deriveAgentSigner(mnemonic, index);
+        const agentWallet = createJinnWalletClient(this.config.rpcUrl, this.chain, agentSigner);
+        // ── Sub-step A: mint NFT (skip if agent_id is already set). ─────────
+        let agentId;
+        if (svc.agent_id) {
+            console.error(`[fleet-bootstrap] Service ${index}: ERC-8004 agent already registered ` +
+                `(agentId=${svc.agent_id}); skipping mint.`);
+            agentId = svc.agent_id;
+            svc = await this.firstServiceUpdate(index, {
+                identity_registry_address: svc.identity_registry_address ?? getAddress(identityRegistry),
+                step: svc.step === 'safe_binding_pending' ? 'safe_binding_pending' : 'agent_registered',
+            });
+        }
+        else {
+            // v0: empty agentURI. The richer agent card (per §6 of the spec) is
+            // future work — operators may later call `setAgentURI`.
+            const agentURI = '';
+            const registerData = encodeFunctionData({
+                abi: IDENTITY_REGISTRY_ABI,
+                functionName: 'register',
+                args: [agentURI],
+            });
+            console.error(`[fleet-bootstrap] Service ${index}: minting ERC-8004 agent NFT ` +
+                `(IdentityRegistry=${identityRegistry}, agentEOA=${agentSigner.address})`);
+            const mintTxHash = await viemSendTransactionWithRetry(agentWallet, this.publicClient, {
+                account: agentSigner,
+                to: addr(identityRegistry),
+                data: registerData,
+            });
+            const receipt = await waitForTransactionReceiptWithRetry(this.publicClient, mintTxHash);
+            if (receipt.status !== 'success') {
+                throw new Error(`IdentityRegistry.register() tx failed for service ${index}: ${mintTxHash}`);
+            }
+            const parsed = this.parseAgentIdFromReceipt(receipt, identityRegistry);
+            if (parsed === null) {
+                throw new Error(`IdentityRegistry.register() succeeded but Registered event was not found ` +
+                    `(service ${index}, tx: ${mintTxHash})`);
+            }
+            agentId = parsed;
+            console.error(`[fleet-bootstrap] Service ${index}: ERC-8004 agent registered ` +
+                `(agentId=${agentId}, tx=${mintTxHash})`);
+            // Persist agentId IMMEDIATELY so a crash between this write and the
+            // setAgentWallet call below does not lose the token.
+            svc = await this.firstServiceUpdate(index, {
+                agent_id: agentId,
+                agent_uri: agentURI,
+                identity_registry_address: getAddress(identityRegistry),
+                agent_registered_tx: mintTxHash,
+                step: 'agent_registered',
+                error: null,
+            });
+        }
+        // ── Sub-step B: bind Safe wallet via ERC-1271 (jinn-mono-aev). ──────
+        // Idempotent: skip when already bound. Requires safe_address — if the
+        // operator is in a topology without a Safe (future), the bind step is
+        // simply not applicable and `safe_bound_to_agent` stays false.
+        if (svc.safe_bound_to_agent) {
+            console.error(`[fleet-bootstrap] Service ${index}: Safe already bound to agentId=${agentId} ` +
+                `(safe=${svc.safe_address}); skipping setAgentWallet.`);
+            svc = await this.firstServiceUpdate(index, {
+                step: 'complete',
+                error: null,
+            });
+        }
+        else if (!svc.safe_address) {
+            console.error(`[fleet-bootstrap] Service ${index}: no safe_address — cannot bind agent NFT ` +
+                `(agentId=${agentId}). Bootstrap will leave safe_bound_to_agent=false; this is ` +
+                `unexpected for the standard staking topology.`);
+            svc = await this.firstServiceUpdate(index, {
+                step: 'safe_binding_pending',
+                error: 'safe_address_missing_for_agent_wallet_binding',
+            });
+        }
+        else {
+            const safeAddress = svc.safe_address;
+            console.error(`[fleet-bootstrap] Service ${index}: binding Safe ${safeAddress} to ` +
+                `agentId=${agentId} via setAgentWallet (ERC-1271).`);
+            svc = await this.firstServiceUpdate(index, {
+                step: 'safe_binding_pending',
+                error: null,
+            });
+            try {
+                const result = await bindAgentWalletToSafe({
+                    identityRegistryAddress: addr(identityRegistry),
+                    agentId: BigInt(agentId),
+                    safeAddress: addr(safeAddress),
+                    agentEoaAccount: agentSigner,
+                    agentEoaWalletClient: agentWallet,
+                    publicClient: this.publicClient,
+                    chainId: this.config.chainId,
+                });
+                console.error(`[fleet-bootstrap] Service ${index}: setAgentWallet succeeded ` +
+                    `(tx=${result.txHash}, safe=${safeAddress}).`);
+                svc = await this.firstServiceUpdate(index, {
+                    safe_bound_to_agent: true,
+                    step: 'complete',
+                    error: null,
+                });
+            }
+            catch (err) {
+                const reason = err instanceof Error ? err.message : String(err);
+                console.error(`[fleet-bootstrap] Service ${index}: setAgentWallet failed; continuing with ` +
+                    `safe_bound_to_agent=false (${reason}).`);
+                svc = await this.firstServiceUpdate(index, {
+                    safe_bound_to_agent: false,
+                    step: 'safe_binding_pending',
+                    error: `safe_binding_failed: ${reason}`,
+                });
+            }
+        }
+        return this.store.load(this.chain);
+    }
+    /**
+     * Tiny store wrapper: re-loads the service row after `updateService` so
+     * the next sub-step sees the latest persisted shape (including any
+     * fields written by sibling code paths since this fn started).
+     */
+    async firstServiceUpdate(index, patch) {
+        await this.store.updateService(index, patch);
+        const fleet = await this.store.load(this.chain);
+        const svc = fleet.services.find(s => s.index === index);
+        if (!svc)
+            throw new Error(`Service ${index} not found after update`);
+        return svc;
+    }
     // ── Self-bond step handlers ──────────────────────────────────────────
     async stepSelfBondSetup(state, mnemonic, index) {
         const svc = state.services.find(s => s.index === index);
@@ -1032,9 +1279,22 @@ export class FleetBootstrapper {
         }
         console.error(`[fleet-bootstrap] Preflight passed: ${slotsRemaining} slots remaining`);
     }
-    async getStakingState(serviceId) {
+    stakingAddressForService(svc) {
+        return addr(svc.staking_address ?? this.config.stakingContract);
+    }
+    shouldPreserveExistingSetup(svc) {
+        if (this.stakingMode !== 'standard' || !svc.staking_address)
+            return false;
+        try {
+            return getAddress(svc.staking_address) !== getAddress(this.config.stakingContract);
+        }
+        catch {
+            return true;
+        }
+    }
+    async getStakingState(serviceId, stakingAddress) {
         return Number(await this.publicClient.readContract({
-            address: this.config.stakingContract,
+            address: addr(stakingAddress ?? this.config.stakingContract),
             abi: STAKING_ABI,
             functionName: 'getStakingState',
             args: [BigInt(serviceId)],
@@ -1075,6 +1335,39 @@ export class FleetBootstrapper {
         }
         return null;
     }
+    /**
+     * Extract `agentId` from an `IdentityRegistry.Registered` log emitted in
+     * the receipt. Filters by `(address, topic[0])` first to avoid colliding
+     * with any other contract that happens to share the event signature.
+     *
+     * Returns the agentId as a decimal string (uint256) so it round-trips
+     * cleanly through JSON-persisted EarningState.
+     */
+    parseAgentIdFromReceipt(receipt, identityRegistry) {
+        const topic = EVENT_TOPICS.Registered;
+        const target = identityRegistry.toLowerCase();
+        for (const log of receipt.logs) {
+            if (log.address.toLowerCase() !== target)
+                continue;
+            if (log.topics[0] !== topic)
+                continue;
+            try {
+                const decoded = decodeEventLog({
+                    abi: IDENTITY_REGISTRY_ABI,
+                    data: log.data,
+                    topics: log.topics,
+                    strict: false,
+                });
+                if (decoded.eventName === 'Registered' && 'agentId' in decoded.args) {
+                    return decoded.args.agentId.toString();
+                }
+            }
+            catch {
+                // Not a matching event
+            }
+        }
+        return null;
+    }
 }
 /** @deprecated Use FleetBootstrapper */
 export const EarningBootstrapper = FleetBootstrapper;