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

package/dist/earning/funding-plan.js

@@ -0,0 +1,203 @@
+/**
+ * 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,
+        testnetClaimRegistryDeploymentPath: options.testnetClaimRegistryDeploymentPath,
+    }), {
+        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 (submit-intent, 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":"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"}

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

@@ -0,0 +1,130 @@
+/**
+ * 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;
+    testnetClaimRegistryDeploymentPath?: string;
+}
+export declare function runLegacyAgentIdMigration(options: RunLegacyAgentIdMigrationOptions): Promise<MigrateAgentIdsResult>;

package/dist/earning/migrate-agent-id.js

@@ -0,0 +1,257 @@
+/**
+ * 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 { decodeEventLog, encodeFunctionData, getAddress, parseAbiItem, } from 'viem';
+import { EVENT_TOPICS, IDENTITY_REGISTRY_ABI, IDENTITY_REGISTRY_ADDRESSES, getChainConfig, } from './contracts.js';
+import { FleetStateStore } from './store.js';
+import { createJinnPublicClient, createJinnWalletClient, } from './viem-clients.js';
+import { decryptMnemonic, deriveAgentSigner, } from './wallet.js';
+import { viemSendTransactionWithRetry, waitForTransactionReceiptWithRetry, } from '../tx-retry.js';
+const REGISTERED_TOPIC = EVENT_TOPICS.Registered;
+/**
+ * Typed `Registered` event item for `publicClient.getLogs({ event, args })`.
+ * The runtime topic hash is identical to `EVENT_TOPICS.Registered` (both are
+ * `keccak256(stringToBytes('Registered(uint256,string,address)'))`).
+ */
+const REGISTERED_EVENT = parseAbiItem('event Registered(uint256 indexed agentId, string agentURI, address indexed owner)');
+/**
+ * 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 async function findAgentIdForOwner(publicClient, identityRegistry, owner, options = {}) {
+    const fromBlock = options.fromBlock ?? 0n;
+    const chunkSize = options.chunkSize ?? 9999n;
+    const latest = await publicClient.getBlockNumber();
+    for (let start = fromBlock; start <= latest; start += chunkSize + 1n) {
+        const end = start + chunkSize > latest ? latest : start + chunkSize;
+        const logs = await publicClient.getLogs({
+            address: identityRegistry,
+            event: REGISTERED_EVENT,
+            args: { owner },
+            fromBlock: start,
+            toBlock: end,
+        });
+        for (const log of logs) {
+            const args = log.args;
+            if (args.agentId === undefined)
+                continue;
+            return {
+                agentId: args.agentId.toString(),
+                agentURI: args.agentURI ?? '',
+                txHash: log.transactionHash ?? '',
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Parse `agentId` from a fresh `IdentityRegistry.register()` receipt.
+ * Mirrors `FleetBootstrapper.parseAgentIdFromReceipt` (private) so we
+ * don't have to re-export the bootstrap class for tests.
+ */
+function parseAgentIdFromReceipt(receipt, identityRegistry) {
+    const target = identityRegistry.toLowerCase();
+    for (const log of receipt.logs) {
+        if (log.address.toLowerCase() !== target)
+            continue;
+        if (log.topics[0] !== REGISTERED_TOPIC)
+            continue;
+        try {
+            const decoded = decodeEventLog({
+                abi: IDENTITY_REGISTRY_ABI,
+                data: log.data,
+                topics: log.topics,
+                strict: false,
+            });
+            if (decoded.eventName !== 'Registered')
+                continue;
+            if (!('agentId' in decoded.args))
+                continue;
+            return {
+                agentId: decoded.args.agentId.toString(),
+                agentURI: 'agentURI' in decoded.args ? String(decoded.args.agentURI ?? '') : '',
+            };
+        }
+        catch {
+            // Not a matching event
+        }
+    }
+    return null;
+}
+/**
+ * Mint a fresh ERC-8004 agent NFT for the agent EOA derived at the
+ * given fleet service index. Used only when the chain-side lookup
+ * confirms no existing token. Returns the parsed agentId + tx hash.
+ *
+ * Mirrors `FleetBootstrapper.stepRegisterAgent` (private), but does
+ * NOT mutate the persisted `step` — the migration writes only to the
+ * agent_id / agent_uri / identity_registry_address / agent_registered_tx
+ * fields and leaves `step` at `complete` so the daemon picks up
+ * normally.
+ */
+async function mintAgentNftForOwner(publicClient, walletClient, account, identityRegistry) {
+    const agentURI = '';
+    const data = encodeFunctionData({
+        abi: IDENTITY_REGISTRY_ABI,
+        functionName: 'register',
+        args: [agentURI],
+    });
+    const txHash = await viemSendTransactionWithRetry(walletClient, publicClient, {
+        account: account,
+        to: identityRegistry,
+        data,
+    });
+    const receipt = await waitForTransactionReceiptWithRetry(publicClient, txHash);
+    if (receipt.status !== 'success') {
+        throw new Error(`IdentityRegistry.register() tx reverted (tx: ${txHash})`);
+    }
+    const parsed = parseAgentIdFromReceipt(receipt, identityRegistry);
+    if (parsed === null) {
+        throw new Error(`IdentityRegistry.register() succeeded but Registered event was not found (tx: ${txHash})`);
+    }
+    return { agentId: parsed.agentId, agentURI: parsed.agentURI, txHash };
+}
+/**
+ * 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 async function migrateAgentIds(deps) {
+    const { stateStore, config, network, mnemonic } = deps;
+    const identityRegistry = config.identityRegistry
+        ?? IDENTITY_REGISTRY_ADDRESSES[config.chainId];
+    if (!identityRegistry) {
+        throw new Error(`IdentityRegistry address not configured for chainId=${config.chainId}; ` +
+            `update IDENTITY_REGISTRY_ADDRESSES in earning/contracts.ts.`);
+    }
+    const registryAddr = getAddress(identityRegistry);
+    const publicClient = deps.publicClient ?? createJinnPublicClient(config.rpcUrl, network);
+    const state = await stateStore.load(network);
+    const migrated = [];
+    const skipped = [];
+    const failed = [];
+    for (const svc of state.services) {
+        if (svc.step !== 'complete')
+            continue;
+        if (svc.agent_id) {
+            skipped.push(svc);
+            continue;
+        }
+        try {
+            const agentSigner = deriveAgentSigner(mnemonic, svc.index);
+            const agentEoa = getAddress(agentSigner.address);
+            // 1. Duplicate-mint guard: scan chain for an existing Registered
+            //    event whose `owner` is this agent EOA. If found, recover
+            //    instead of minting (DR §4.1).
+            const existing = await findAgentIdForOwner(publicClient, registryAddr, agentEoa, {
+                fromBlock: deps.scanFromBlock,
+                chunkSize: deps.scanChunkSize,
+            });
+            let agentId;
+            let agentURI;
+            let txHash;
+            if (existing) {
+                console.error(`[migrate-agent-id] Service ${svc.index}: recovered existing agentId=${existing.agentId} ` +
+                    `for agent EOA ${agentEoa} (tx=${existing.txHash || 'unknown'}); no mint needed.`);
+                agentId = existing.agentId;
+                agentURI = existing.agentURI;
+                txHash = existing.txHash;
+            }
+            else {
+                console.error(`[migrate-agent-id] Service ${svc.index}: minting ERC-8004 agent NFT ` +
+                    `(IdentityRegistry=${registryAddr}, agentEOA=${agentEoa})`);
+                const walletClient = deps.walletClientFactory?.(agentSigner)
+                    ?? createJinnWalletClient(config.rpcUrl, network, agentSigner);
+                const minted = await mintAgentNftForOwner(publicClient, walletClient, agentSigner, registryAddr);
+                agentId = minted.agentId;
+                agentURI = minted.agentURI;
+                txHash = minted.txHash;
+                console.error(`[migrate-agent-id] Service ${svc.index}: minted agentId=${agentId} (tx=${txHash})`);
+            }
+            // Persist immediately. We deliberately leave `step: 'complete'` —
+            // the migration's job is purely to backfill the agent fields, not
+            // to rewind the state machine. The daemon (main.ts) reads agent_id
+            // from the loaded state and wires the IdentityPublisher accordingly.
+            await stateStore.updateService(svc.index, {
+                agent_id: agentId,
+                agent_uri: agentURI,
+                identity_registry_address: registryAddr,
+                agent_registered_tx: txHash || null,
+                // Keep safe_bound_to_agent at its persisted value (default false);
+                // setAgentWallet is tracked by jinn-mono-aev.
+            });
+            const refreshed = (await stateStore.load(network)).services.find(s => s.index === svc.index);
+            if (refreshed) {
+                migrated.push(refreshed);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[migrate-agent-id] Service ${svc.index}: migration failed — ${message}`);
+            failed.push({ service: svc, error: message });
+        }
+    }
+    return { migrated, skipped, failed };
+}
+export async function runLegacyAgentIdMigration(options) {
+    const stateStore = new FleetStateStore(options.earningDir);
+    const config = getChainConfig(options.network, {
+        testnetL2DeploymentPath: options.testnetL2DeploymentPath,
+        testnetL2TokenDeploymentPath: options.testnetL2TokenDeploymentPath,
+        testnetMechDeploymentPath: options.testnetMechDeploymentPath,
+        testnetStolasDeploymentPath: options.testnetStolasDeploymentPath,
+        testnetClaimRegistryDeploymentPath: options.testnetClaimRegistryDeploymentPath,
+    });
+    config.rpcUrl = options.rpcUrl;
+    const mnemonic = await decryptMnemonic(await stateStore.loadMnemonicKeystore(), options.password);
+    return migrateAgentIds({
+        stateStore,
+        config,
+        network: options.network,
+        mnemonic,
+    });
+}
+//# sourceMappingURL=migrate-agent-id.js.map

package/dist/earning/migrate-agent-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-agent-id.js","sourceRoot":"","sources":["../../src/earning/migrate-agent-id.ts"],"names":[],"mappings":"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"}

package/dist/earning/orphan-sweep.d.ts

@@ -14,6 +14,13 @@ import type { PublicClient } from 'viem';
  * address that will no longer be tracked so we can sweep it first.
  */
 export declare function previousSafeBeingAbandoned(svc: ServiceState, patch: Partial<ServiceState>): string | null;
+/** An ERC-20 token to sweep from the abandoned Safe. */
+export interface Erc20SweepToken {
+    /** Checksummed token contract address. */
+    address: string;
+    /** Human-readable symbol for log messages. */
+    symbol: string;
+}
 export interface SweepOrphanedServiceFundsParams {
     rpcUrl: string;
     network: JinnOnchainNetwork;
@@ -25,6 +32,13 @@ export interface SweepOrphanedServiceFundsParams {
     agentAddress: string;
     abandonedSafeAddress: string;
     minAgentReserveWei: bigint;
+    /**
+     * ERC-20 tokens to sweep from the abandoned Safe (e.g. OLAS bond).
+     * Each token with a non-zero balance on the Safe will be transferred
+     * to `masterAddress` via Safe.execTransaction. If omitted, no ERC-20
+     * sweep is attempted.
+     */
+    erc20Tokens?: Erc20SweepToken[];
 }
 /**
  * Sweep ETH from an abandoned deployed Safe (via Safe.execTransaction) and excess