@jinn-network/client 0.1.2 → 0.1.3-canary.24b69ea4

package/dist/earning/funding-plan.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Read-only funding plan for the fleet bootstrap state machine.
+ *
+ * `jinn fund-requirements` (and other inspection callers) need to learn
+ * "what funding gates are blocking us right now?" without mutating any
+ * state. Specifically: never write to the fleet store, never request
+ * faucet funds, never send any chain transactions, never advance the
+ * bootstrap state machine.
+ *
+ * The mutating counterpart lives in `FleetBootstrapper.bootstrap()` and
+ * is invoked by `jinn bootstrap`/`jinn run`.
+ *
+ * See: docs/reviews/2026-04-28-operator-experience-audit.md (W1).
+ */
+import { type PublicClient } from 'viem';
+import { getChainConfig } from './contracts.js';
+import { FleetStateStore } from './store.js';
+import { type FleetState, type FundingRequirement, type StakingMode } from './types.js';
+import { type JinnOnchainNetwork } from './viem-clients.js';
+export interface FundingPlanOptions {
+    earningDir?: string;
+    chain?: JinnOnchainNetwork;
+    rpcUrl?: string;
+    stakingMode?: StakingMode;
+    targetServices?: number;
+    testnetL2DeploymentPath?: string;
+    testnetL2TokenDeploymentPath?: string;
+    testnetMechDeploymentPath?: string;
+    testnetStolasDeploymentPath?: string;
+    minEoaGasWei?: string;
+    minSafeEthWei?: string;
+    /** Optional password — without it we cannot derive the master address from a keystore. */
+    password?: string;
+    /** Inject a public client (tests). Defaults to a viem client over rpcUrl. */
+    publicClientFactory?: (rpcUrl: string, network: JinnOnchainNetwork) => PublicClient;
+    /** Inject the fleet store (tests). */
+    storeFactory?: (earningDir?: string) => FleetStateStore;
+    /** Inject chain config (tests). */
+    chainConfigResolver?: typeof getChainConfig;
+}
+/** A single per-Safe ETH gap, surfaced for runtime mech-fee paths. */
+export interface SafeFundingRow {
+    serviceIndex: number;
+    safeAddress: string;
+    haveWei: string;
+    needWei: string;
+    asset: 'native';
+    reason: string;
+}
+/** Reasons the plan is partial — the answer is best-effort, not authoritative. */
+export type FundingPlanPartialReason = 'no_keystore' | 'password_missing' | 'password_invalid' | 'rpc_unreachable' | 'fleet_state_missing' | 'fleet_state_invalid';
+export interface FundingPlan {
+    /**
+     * Best-effort assessment that no funding gate is currently blocking advancement.
+     * This is `false` whenever any requirement is present OR the answer is partial.
+     */
+    satisfied: boolean;
+    /**
+     * `true` when the plan could not fully evaluate the funding state. Operators
+     * (and agents) should treat the result as advisory and re-run after fixing
+     * the listed reasons. The plan never mutates state.
+     */
+    partial: boolean;
+    reasons: FundingPlanPartialReason[];
+    /**
+     * Master-level shortfall when the master EOA does not yet hold the
+     * minimum ETH the bootstrap state machine needs to proceed.
+     */
+    master?: FundingRequirement;
+    /** Per-Safe ETH gaps for completed services (for runtime mech-fee paths). */
+    safes: SafeFundingRow[];
+    /** Snapshot of the fleet state used for evaluation, when available. */
+    fleetState?: FleetState;
+}
+/**
+ * Compute the read-only funding plan. Pure function over disk + chain reads.
+ *
+ * Guarantees (these are part of the contract relied on by `jinn fund-requirements`):
+ *   - Never writes to the fleet state file or keystore.
+ *   - Never requests faucet funds.
+ *   - Never sends any chain transactions.
+ *
+ * If a password is provided and a mnemonic keystore exists, the master
+ * address is derived from the keystore for funding evaluation. If the
+ * password is missing, wrong, or no keystore exists, the plan still
+ * returns whatever it can learn from disk + chain reads, with a partial
+ * flag and machine-readable reasons.
+ */
+export declare function planFleetFunding(options?: FundingPlanOptions): Promise<FundingPlan>;

package/dist/earning/funding-plan.js

@@ -0,0 +1,202 @@
+/**
+ * Read-only funding plan for the fleet bootstrap state machine.
+ *
+ * `jinn fund-requirements` (and other inspection callers) need to learn
+ * "what funding gates are blocking us right now?" without mutating any
+ * state. Specifically: never write to the fleet store, never request
+ * faucet funds, never send any chain transactions, never advance the
+ * bootstrap state machine.
+ *
+ * The mutating counterpart lives in `FleetBootstrapper.bootstrap()` and
+ * is invoked by `jinn bootstrap`/`jinn run`.
+ *
+ * See: docs/reviews/2026-04-28-operator-experience-audit.md (W1).
+ */
+import { getAddress } from 'viem';
+import { applyChainGasOverrides, getChainConfig, } from './contracts.js';
+import { FleetStateStore } from './store.js';
+import { decryptMnemonic, deriveMasterAddress } from './wallet.js';
+import { isOperationalServiceStep } from './types.js';
+import { createJinnPublicClient } from './viem-clients.js';
+const SELF_BOND_ETH_PER_SERVICE = 30000000000000000n; // 0.03 ETH
+const STANDARD_MASTER_BOOTSTRAP_MULTIPLIER = 2n;
+const addr = (value) => getAddress(value);
+async function safeGetBalance(client, address) {
+    try {
+        return await client.getBalance({ address });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compute the read-only funding plan. Pure function over disk + chain reads.
+ *
+ * Guarantees (these are part of the contract relied on by `jinn fund-requirements`):
+ *   - Never writes to the fleet state file or keystore.
+ *   - Never requests faucet funds.
+ *   - Never sends any chain transactions.
+ *
+ * If a password is provided and a mnemonic keystore exists, the master
+ * address is derived from the keystore for funding evaluation. If the
+ * password is missing, wrong, or no keystore exists, the plan still
+ * returns whatever it can learn from disk + chain reads, with a partial
+ * flag and machine-readable reasons.
+ */
+export async function planFleetFunding(options = {}) {
+    const chain = options.chain ?? 'base';
+    const stakingMode = options.stakingMode ?? 'standard';
+    const targetServices = options.targetServices ?? 1;
+    const reasons = [];
+    const storeFactory = options.storeFactory ?? ((dir) => new FleetStateStore(dir));
+    const store = storeFactory(options.earningDir);
+    const chainConfigResolver = options.chainConfigResolver ?? getChainConfig;
+    const config = applyChainGasOverrides(chainConfigResolver(chain, {
+        testnetL2DeploymentPath: options.testnetL2DeploymentPath,
+        testnetL2TokenDeploymentPath: options.testnetL2TokenDeploymentPath,
+        testnetMechDeploymentPath: options.testnetMechDeploymentPath,
+        testnetStolasDeploymentPath: options.testnetStolasDeploymentPath,
+    }), {
+        minEoaGasWei: options.minEoaGasWei,
+        minSafeEthWei: options.minSafeEthWei,
+    });
+    if (options.rpcUrl) {
+        config.rpcUrl = options.rpcUrl;
+    }
+    const publicClientFactory = options.publicClientFactory ?? ((url, net) => createJinnPublicClient(url, net));
+    const publicClient = publicClientFactory(config.rpcUrl, chain);
+    // Read-only fleet state probe. We deliberately call `tryLoadExisting`
+    // (never `load`) — `load` writes a default file when the state is
+    // missing, which would be a mutation.
+    const fleetState = await store.tryLoadExisting();
+    if (!fleetState) {
+        reasons.push('fleet_state_missing');
+    }
+    // Resolve master address: prefer persisted state, then derive from
+    // keystore + password if available, otherwise mark partial.
+    let masterAddress = null;
+    if (fleetState?.master_address) {
+        masterAddress = addr(fleetState.master_address);
+    }
+    else if (store.hasMnemonicKeystore()) {
+        if (options.password) {
+            try {
+                const ks = await store.loadMnemonicKeystore();
+                const mnemonic = await decryptMnemonic(ks, options.password);
+                masterAddress = addr(deriveMasterAddress(mnemonic));
+            }
+            catch {
+                reasons.push('password_invalid');
+            }
+        }
+        else {
+            reasons.push('password_missing');
+        }
+    }
+    else {
+        reasons.push('no_keystore');
+    }
+    // No master => no useful master-level evaluation possible.
+    if (!masterAddress) {
+        return {
+            satisfied: false,
+            partial: true,
+            reasons,
+            safes: [],
+            fleetState: fleetState ?? undefined,
+        };
+    }
+    // Master ETH probe.
+    const masterBalance = await safeGetBalance(publicClient, masterAddress);
+    if (masterBalance === null) {
+        reasons.push('rpc_unreachable');
+        return {
+            satisfied: false,
+            partial: true,
+            reasons,
+            safes: [],
+            fleetState: fleetState ?? undefined,
+        };
+    }
+    let systemEth = masterBalance;
+    if (stakingMode === 'self-bond' && fleetState) {
+        for (const svc of fleetState.services) {
+            if (svc.agent_address) {
+                const bal = await safeGetBalance(publicClient, addr(svc.agent_address));
+                if (bal === null) {
+                    reasons.push('rpc_unreachable');
+                }
+                else {
+                    systemEth += bal;
+                }
+            }
+            if (svc.safe_address) {
+                const bal = await safeGetBalance(publicClient, addr(svc.safe_address));
+                if (bal === null) {
+                    reasons.push('rpc_unreachable');
+                }
+                else {
+                    systemEth += bal;
+                }
+            }
+        }
+    }
+    const completedCount = fleetState?.services.filter((svc) => isOperationalServiceStep(svc.step)).length ?? 0;
+    const standardFleetAlreadyComplete = stakingMode === 'standard' && completedCount >= targetServices;
+    const standardFleetHasInProgressServices = stakingMode === 'standard' && (fleetState?.services.length ?? 0) > 0;
+    const requiredMasterEth = stakingMode === 'standard'
+        ? (standardFleetAlreadyComplete
+            ? 0n
+            : config.minEoaGasEth * (standardFleetHasInProgressServices ? 1n : STANDARD_MASTER_BOOTSTRAP_MULTIPLIER))
+        : SELF_BOND_ETH_PER_SERVICE * BigInt(targetServices);
+    let master;
+    if (systemEth < requiredMasterEth) {
+        const shortfall = requiredMasterEth - systemEth;
+        master = {
+            master_address: masterAddress,
+            eth_required: shortfall.toString(),
+            eth_balance: masterBalance.toString(),
+        };
+    }
+    // Per-Safe probes for completed services (parity with the existing
+    // mech-fee runtime probe in fund-requirements). Only emitted when
+    // master-level funding is satisfied — same as the prior behaviour.
+    const safes = [];
+    if (!master && fleetState) {
+        for (const svc of fleetState.services) {
+            if (!isOperationalServiceStep(svc.step) || !svc.safe_address)
+                continue;
+            const safeAddr = addr(svc.safe_address);
+            const bal = await safeGetBalance(publicClient, safeAddr);
+            if (bal === null) {
+                reasons.push('rpc_unreachable');
+                continue;
+            }
+            if (bal >= config.minSafeEth)
+                continue;
+            safes.push({
+                serviceIndex: svc.index,
+                safeAddress: safeAddr,
+                haveWei: bal.toString(),
+                needWei: (config.minSafeEth - bal).toString(),
+                asset: 'native',
+                reason: `Service ${svc.index} Safe needs native ETH to pay mech fees (each evaluation job sends 99 wei). ` +
+                    `The daemon's balance-topup-loop auto-refills from master at runtime; funding it manually is ` +
+                    `required only when running CLI verbs (tasks submit, acceptance gate) outside the daemon.`,
+            });
+        }
+    }
+    // Deduplicate reasons (rpc_unreachable can be appended multiple times).
+    const uniqueReasons = Array.from(new Set(reasons));
+    const partial = uniqueReasons.length > 0;
+    const satisfied = !master && safes.length === 0 && !partial;
+    return {
+        satisfied,
+        partial,
+        reasons: uniqueReasons,
+        master,
+        safes,
+        fleetState: fleetState ?? undefined,
+    };
+}
+//# sourceMappingURL=funding-plan.js.map

package/dist/earning/funding-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"funding-plan.js","sourceRoot":"","sources":["../../src/earning/funding-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,UAAU,EAAmC,MAAM,MAAM,CAAC;AACnE,OAAO,EAEL,sBAAsB,EACtB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAA8D,MAAM,YAAY,CAAC;AAClH,OAAO,EAAE,sBAAsB,EAA2B,MAAM,mBAAmB,CAAC;AAmEpF,MAAM,yBAAyB,GAAG,kBAAuB,CAAC,CAAC,WAAW;AACtE,MAAM,oCAAoC,GAAG,EAAE,CAAC;AAEhD,MAAM,IAAI,GAAG,CAAC,KAAa,EAAW,EAAE,CAAC,UAAU,CAAC,KAAK,CAAY,CAAC;AAEtE,KAAK,UAAU,cAAc,CAC3B,MAAoB,EACpB,OAAgB;IAEhB,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,UAA8B,EAAE;IAEhC,MAAM,KAAK,GAAuB,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC;IAC1D,MAAM,WAAW,GAAgB,OAAO,CAAC,WAAW,IAAI,UAAU,CAAC;IACnE,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,CAAC,CAAC;IACnD,MAAM,OAAO,GAA+B,EAAE,CAAC;IAE/C,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC;IACjF,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAE/C,MAAM,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,IAAI,cAAc,CAAC;IAC1E,MAAM,MAAM,GAAgB,sBAAsB,CAAC,mBAAmB,CAAC,KAAK,EAAE;QAC5E,uBAAuB,EAAE,OAAO,CAAC,uBAAuB;QACxD,4BAA4B,EAAE,OAAO,CAAC,4BAA4B;QAClE,yBAAyB,EAAE,OAAO,CAAC,yBAAyB;QAC5D,2BAA2B,EAAE,OAAO,CAAC,2BAA2B;KACjE,CAAC,EAAE;QACF,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,aAAa,EAAE,OAAO,CAAC,aAAa;KACrC,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IACjC,CAAC;IAED,MAAM,mBAAmB,GACvB,OAAO,CAAC,mBAAmB,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,sBAAsB,CAAC,GAAG,EAAE,GAAG,CAA4B,CAAC,CAAC;IAC7G,MAAM,YAAY,GAAG,mBAAmB,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAE/D,sEAAsE;IACtE,kEAAkE;IAClE,sCAAsC;IACtC,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,eAAe,EAAE,CAAC;IACjD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IACtC,CAAC;IAED,mEAAmE;IACnE,4DAA4D;IAC5D,IAAI,aAAa,GAAmB,IAAI,CAAC;IACzC,IAAI,UAAU,EAAE,cAAc,EAAE,CAAC;QAC/B,aAAa,GAAG,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;IAClD,CAAC;SAAM,IAAI,KAAK,CAAC,mBAAmB,EAAE,EAAE,CAAC;QACvC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACrB,IAAI,CAAC;gBACH,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,oBAAoB,EAAE,CAAC;gBAC9C,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,EAAE,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAC7D,aAAa,GAAG,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,CAAC;YACtD,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC9B,CAAC;IAED,2DAA2D;IAC3D,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,OAAO;YACL,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,IAAI;YACb,OAAO;YACP,KAAK,EAAE,EAAE;YACT,UAAU,EAAE,UAAU,IAAI,SAAS;SACpC,CAAC;IACJ,CAAC;IAED,oBAAoB;IACpB,MAAM,aAAa,GAAG,MAAM,cAAc,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;IACxE,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;QAC3B,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAChC,OAAO;YACL,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,IAAI;YACb,OAAO;YACP,KAAK,EAAE,EAAE;YACT,UAAU,EAAE,UAAU,IAAI,SAAS;SACpC,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,GAAG,aAAa,CAAC;IAC9B,IAAI,WAAW,KAAK,WAAW,IAAI,UAAU,EAAE,CAAC;QAC9C,KAAK,MAAM,GAAG,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC;YACtC,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;gBACtB,MAAM,GAAG,GAAG,MAAM,cAAc,CAAC,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;gBACxE,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;oBACjB,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;gBAClC,CAAC;qBAAM,CAAC;oBACN,SAAS,IAAI,GAAG,CAAC;gBACnB,CAAC;YACH,CAAC;YACD,IAAI,GAAG,CAAC,YAAY,EAAE,CAAC;gBACrB,MAAM,GAAG,GAAG,MAAM,cAAc,CAAC,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC;gBACvE,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;oBACjB,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;gBAClC,CAAC;qBAAM,CAAC;oBACN,SAAS,IAAI,GAAG,CAAC;gBACnB,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,cAAc,GAAG,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;IAC5G,MAAM,4BAA4B,GAAG,WAAW,KAAK,UAAU,IAAI,cAAc,IAAI,cAAc,CAAC;IACpG,MAAM,kCAAkC,GACtC,WAAW,KAAK,UAAU,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACvE,MAAM,iBAAiB,GACrB,WAAW,KAAK,UAAU;QACxB,CAAC,CAAC,CACE,4BAA4B;YAC1B,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,MAAM,CAAC,YAAY,GAAG,CAAC,kCAAkC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,oCAAoC,CAAC,CAC3G;QACH,CAAC,CAAC,yBAAyB,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;IAEzD,IAAI,MAAsC,CAAC;IAC3C,IAAI,SAAS,GAAG,iBAAiB,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,iBAAiB,GAAG,SAAS,CAAC;QAChD,MAAM,GAAG;YACP,cAAc,EAAE,aAAa;YAC7B,YAAY,EAAE,SAAS,CAAC,QAAQ,EAAE;YAClC,WAAW,EAAE,aAAa,CAAC,QAAQ,EAAE;SACtC,CAAC;IACJ,CAAC;IAED,mEAAmE;IACnE,kEAAkE;IAClE,mEAAmE;IACnE,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,IAAI,CAAC,MAAM,IAAI,UAAU,EAAE,CAAC;QAC1B,KAAK,MAAM,GAAG,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC;YACtC,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY;gBAAE,SAAS;YACvE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YACxC,MAAM,GAAG,GAAG,MAAM,cAAc,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;YACzD,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;gBACjB,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;gBAChC,SAAS;YACX,CAAC;YACD,IAAI,GAAG,IAAI,MAAM,CAAC,UAAU;gBAAE,SAAS;YACvC,KAAK,CAAC,IAAI,CAAC;gBACT,YAAY,EAAE,GAAG,CAAC,KAAK;gBACvB,WAAW,EAAE,QAAQ;gBACrB,OAAO,EAAE,GAAG,CAAC,QAAQ,EAAE;gBACvB,OAAO,EAAE,CAAC,MAAM,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,QAAQ,EAAE;gBAC7C,KAAK,EAAE,QAAQ;gBACf,MAAM,EACJ,WAAW,GAAG,CAAC,KAAK,8EAA8E;oBAClG,8FAA8F;oBAC9F,0FAA0F;aAC7F,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,wEAAwE;IACxE,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACnD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC;IAE5D,OAAO;QACL,SAAS;QACT,OAAO;QACP,OAAO,EAAE,aAAa;QACtB,MAAM;QACN,KAAK;QACL,UAAU,EAAE,UAAU,IAAI,SAAS;KACpC,CAAC;AACJ,CAAC"}

package/dist/earning/migrate-agent-id.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Legacy backfill: ERC-8004 IdentityRegistry mint for `complete` services
+ * that pre-date jinn-mono-j07.
+ *
+ * j07 added an `agent_registered` step to the bootstrap state machine,
+ * slotted between `mech_deployed` and `complete`. Operators that completed
+ * bootstrap BEFORE j07 landed have `state == 'complete' && agent_id == null`
+ * and are stuck — they cannot publish per-execution metadata via
+ * `setMetadata` (jinn-mono-3zk wires that, but it is gated on a non-null
+ * `agent_id`).
+ *
+ * This module detects such services and runs the agent-registration mint
+ * idempotently for each. It is safe to re-run: services that already have
+ * an `agent_id` are skipped, and a chain-side lookup recovers the existing
+ * agentId for any operator whose state file was lost but whose Safe still
+ * owns the NFT (per the entity-model decision record §4.1, the operator
+ * agent NFT is stable across executions / re-stakes — we MUST never
+ * mint a duplicate).
+ *
+ * Wired in two places:
+ *   - daemon startup (`main.ts` after `bootstrap`), gated by
+ *     `runLegacyMigrations` config flag (default true)
+ *   - explicit CLI subcommand `jinn migrate-agent-id`
+ *
+ * Tracked as jinn-mono-jgp.
+ */
+import { type Address, type PublicClient, type WalletClient } from 'viem';
+import { type ChainConfig } from './contracts.js';
+import { FleetStateStore } from './store.js';
+import { type JinnOnchainNetwork } from './viem-clients.js';
+import { deriveAgentSigner } from './wallet.js';
+import type { ServiceState } from './types.js';
+export interface MigrateAgentIdsDeps {
+    /** Persistence layer for fleet state. */
+    stateStore: FleetStateStore;
+    /** Resolved chain config (identity registry, RPC URL, chain ID). */
+    config: ChainConfig;
+    /** Network the chain config is for. */
+    network: JinnOnchainNetwork;
+    /** Decrypted HD mnemonic for the master wallet (used to derive agent signers). */
+    mnemonic: string;
+    /**
+     * Optional override for the public client (tests). Defaults to a fresh
+     * client built from `config.rpcUrl` + `network`.
+     */
+    publicClient?: PublicClient;
+    /**
+     * Optional factory for wallet clients (tests). Defaults to the production
+     * `createJinnWalletClient`. Receives the agent EOA private-key account.
+     */
+    walletClientFactory?: (account: ReturnType<typeof deriveAgentSigner>) => WalletClient;
+    /**
+     * Lower bound for the `Registered` event scan. Mainnet/testnet defaults are
+     * adequate; tests override to keep mocks compact. The scan walks forward
+     * from this block to `latest` in chunks.
+     */
+    scanFromBlock?: bigint;
+    /**
+     * Block-range chunk size for the `getLogs` scan. Defaults to 9_999n
+     * (under typical RPC limits like Alchemy's 10k cap).
+     */
+    scanChunkSize?: bigint;
+}
+export interface MigrateAgentIdsFailure {
+    service: ServiceState;
+    error: string;
+}
+export interface MigrateAgentIdsResult {
+    /** Services that were successfully migrated this run (state file updated). */
+    migrated: ServiceState[];
+    /** Services with `state == 'complete'` and `agent_id` already populated. */
+    skipped: ServiceState[];
+    /** Services that failed migration; the rest of the run continues. */
+    failed: MigrateAgentIdsFailure[];
+}
+/**
+ * Scan past `Registered(uint256 indexed agentId, string agentURI, address indexed owner)`
+ * events on the IdentityRegistry, filtered by indexed `owner`, and return
+ * the most recent agentId minted for that owner (or null if none).
+ *
+ * This is the duplicate-mint guard: per DR §4.1, the operator agent NFT
+ * is stable across executions and survives Safe rotation. If an
+ * operator's state file lost the `agent_id` (e.g. corrupted backup),
+ * we MUST recover the existing token rather than minting a new one.
+ *
+ * The scan uses the indexed `owner` topic so the RPC can return only
+ * matching logs cheaply. We chunk by `scanChunkSize` to stay under
+ * provider log-limit caps. The mint is one-shot per owner in our flow,
+ * so we expect 0 or 1 hits.
+ */
+export declare function findAgentIdForOwner(publicClient: PublicClient, identityRegistry: Address, owner: Address, options?: {
+    fromBlock?: bigint;
+    chunkSize?: bigint;
+}): Promise<{
+    agentId: string;
+    agentURI: string;
+    txHash: string;
+} | null>;
+/**
+ * Backfill `agent_id` on every service whose state is `complete` but
+ * which has no persisted agentId.
+ *
+ * Behaviour:
+ *   - `state == 'complete' && agent_id == null` → migrated (recover existing
+ *     NFT from chain if the agent EOA already owns one, else mint a new one).
+ *   - `state == 'complete' && agent_id != null` → skipped.
+ *   - any other step → ignored (the normal `stepRegisterAgent` path handles
+ *     them when bootstrap resumes).
+ *
+ * Failures are isolated per service; one mint reverting does not abort
+ * the rest of the migration.
+ */
+export declare function migrateAgentIds(deps: MigrateAgentIdsDeps): Promise<MigrateAgentIdsResult>;
+/**
+ * Convenience wrapper: build deps from a config-shaped object + password
+ * and run the migration. Used by main.ts (daemon startup) and the CLI
+ * subcommand. Tests call `migrateAgentIds` directly with mocked deps.
+ */
+export interface RunLegacyAgentIdMigrationOptions {
+    earningDir: string;
+    network: JinnOnchainNetwork;
+    rpcUrl: string;
+    password: string;
+    testnetL2DeploymentPath?: string;
+    testnetL2TokenDeploymentPath?: string;
+    testnetMechDeploymentPath?: string;
+    testnetStolasDeploymentPath?: string;
+}
+export declare function runLegacyAgentIdMigration(options: RunLegacyAgentIdMigrationOptions): Promise<MigrateAgentIdsResult>;