@clanker-chain/clanker-cli 2026.9.7 → 2026.9.8-2

package/lib/doctor.mjs

@@ -0,0 +1,226 @@
+/**
+ * `clanker doctor` — local readiness checks (mise-doctor habit).
+ */
+
+import { getAddress } from "viem";
+import {
+  ANVIL_DEFAULT_ADDRESS,
+  isLocalRpc,
+  loadConfig,
+  loadOperator,
+  clankerHome,
+} from "./profile.mjs";
+import { detectSetupHints, formatSetupDetectTable } from "./setup-detect.mjs";
+import { c, nextHint } from "./ui.mjs";
+
+/**
+ * @param {{ home?: string, env?: NodeJS.ProcessEnv, openclawDir?: string, castBin?: string, spawn?: Function, fetchImpl?: typeof fetch }} [opts]
+ */
+export async function runDoctorChecks(opts = {}) {
+  const env = opts.env ?? process.env;
+  const home = opts.home ?? clankerHome(env);
+  const hints = detectSetupHints({
+    home,
+    env,
+    openclawDir: opts.openclawDir,
+    castBin: opts.castBin,
+    spawn: opts.spawn,
+  });
+  const config = hints.config ?? loadConfig(home);
+  const operator = hints.operator ?? loadOperator(home);
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+
+  /** @type {{ id: string, ok: boolean, level: 'pass'|'warn'|'fail', message: string }[]} */
+  const checks = [];
+
+  checks.push({
+    id: "config",
+    ok: Boolean(config),
+    level: config ? "pass" : "fail",
+    message: config
+      ? `config.json present (preset=${config.preset})`
+      : "config.json missing — run clanker setup",
+  });
+
+  const registry = config?.registryAddress;
+  const rpc = config?.chainRpcUrl ?? "";
+  checks.push({
+    id: "registry",
+    ok: Boolean(registry && /^0x[0-9a-fA-F]{40}$/.test(registry)),
+    level: registry && /^0x[0-9a-fA-F]{40}$/.test(registry) ? "pass" : "fail",
+    message:
+      registry && /^0x[0-9a-fA-F]{40}$/.test(registry)
+        ? `registry ${registry}`
+        : "registry missing — run clanker setup --preset sepolia (or set after local deploy)",
+  });
+
+  const hasOwner =
+    Boolean(operator?.owner) && /^0x[0-9a-fA-F]{40}$/.test(operator.owner);
+  const hasLabel = Boolean(operator?.label);
+  checks.push({
+    id: "operator",
+    ok: hasOwner && hasLabel,
+    level: hasOwner && hasLabel ? "pass" : "fail",
+    message:
+      hasOwner && hasLabel
+        ? `operator.json ${operator.label} · ${operator.owner}`
+        : "operator.json incomplete — run clanker setup",
+  });
+
+  if (hasOwner && rpc && !isLocalRpc(rpc)) {
+    const anvil =
+      getAddress(operator.owner).toLowerCase() ===
+      ANVIL_DEFAULT_ADDRESS.toLowerCase();
+    checks.push({
+      id: "anvil_public",
+      ok: !anvil,
+      level: anvil ? "fail" : "pass",
+      message: anvil
+        ? "owner is Anvil #0 on a public RPC — refuse for mutate; fix owner address"
+        : "owner is not Anvil #0",
+    });
+  }
+
+  const hasKey =
+    Boolean(operator?.key?.type === "keyFile" && operator.key.value) ||
+    Boolean(operator?.key?.type === "env" && operator.key.value) ||
+    Boolean(env.OPERATOR_PRIVATE_KEY);
+  checks.push({
+    id: "signing",
+    ok: true,
+    level: hasKey ? "pass" : "warn",
+    message: hasKey
+      ? "signing key pointer available (mint/revoke OK)"
+      : "read-only profile — whoami/bots OK; mint needs --key-file or OPERATOR_PRIVATE_KEY",
+  });
+
+  checks.push({
+    id: "foundry",
+    ok: true,
+    level: hints.foundryAvailable ? "pass" : "warn",
+    message: hints.foundryAvailable
+      ? `Foundry cast OK (${hints.foundryAccounts.length} account(s))`
+      : "Foundry cast not on PATH (optional)",
+  });
+
+  const authUrl = config?.mqttAuthServiceUrl;
+  if (authUrl && typeof fetchImpl === "function") {
+    const healthUrl = `${String(authUrl).replace(/\/$/, "")}/health`;
+    try {
+      const ac = new AbortController();
+      const t = setTimeout(() => ac.abort(), 5000);
+      const res = await fetchImpl(healthUrl, { signal: ac.signal });
+      clearTimeout(t);
+      if (res.ok) {
+        checks.push({
+          id: "mqtt_auth_health",
+          ok: true,
+          level: "pass",
+          message: `mqtt-auth health OK (${healthUrl})`,
+        });
+      } else {
+        checks.push({
+          id: "mqtt_auth_health",
+          ok: false,
+          level: "fail",
+          message: `mqtt-auth health HTTP ${res.status} (${healthUrl})`,
+        });
+      }
+    } catch (err) {
+      checks.push({
+        id: "mqtt_auth_health",
+        ok: false,
+        level: "warn",
+        message: `mqtt-auth health unreachable: ${err.message ?? err}`,
+      });
+    }
+  } else if (config) {
+    checks.push({
+      id: "mqtt_auth_health",
+      ok: true,
+      level: "warn",
+      message: "mqttAuthServiceUrl not set — skip hub health",
+    });
+  }
+
+  const readyWhoami = checks
+    .filter((ch) => ch.id === "config" || ch.id === "registry" || ch.id === "operator")
+    .every((ch) => ch.ok);
+  const readyMint = readyWhoami && hasKey &&
+    !checks.some((ch) => ch.id === "anvil_public" && !ch.ok);
+
+  return {
+    home,
+    hints,
+    checks,
+    readyWhoami,
+    readyMint,
+    ok: readyWhoami,
+  };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ home?: string, env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {Promise<{ exitCode: number, report: object }>}
+ */
+export async function runDoctor(argv = [], opts = {}) {
+  const json = argv.includes("--json");
+  const report = await runDoctorChecks(opts);
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: report.ok,
+          readyWhoami: report.readyWhoami,
+          readyMint: report.readyMint,
+          home: report.home,
+          checks: report.checks,
+        },
+        null,
+        2,
+      ),
+    );
+    return { exitCode: report.ok ? 0 : 1, report };
+  }
+
+  console.log(c.bold("clanker doctor"));
+  console.log("");
+  console.log(formatSetupDetectTable(report.hints));
+  console.log("");
+  console.log(c.bold("Checks"));
+  for (const ch of report.checks) {
+    const mark =
+      ch.level === "pass"
+        ? c.green("pass")
+        : ch.level === "warn"
+          ? c.yellow("warn")
+          : c.red("fail");
+    console.log(`  [${mark}] ${ch.message}`);
+  }
+  console.log("");
+  if (report.readyWhoami) {
+    console.log(c.green("Ready for: clanker whoami"));
+  } else {
+    console.log(c.red("Not ready for whoami"));
+  }
+  if (report.readyMint) {
+    console.log(c.green("Ready for: clanker operator mint / bot mint"));
+  } else {
+    console.log(c.dim("Mint/revoke: need signing key (and non-Anvil owner on public RPC)"));
+  }
+
+  if (!report.readyWhoami) {
+    nextHint(["clanker setup"]);
+  } else if (!report.readyMint) {
+    nextHint([
+      "clanker whoami",
+      "clanker setup --key-file ~/.clanker/op.key --force   # to enable mint",
+    ]);
+  } else {
+    nextHint(["clanker whoami", "clanker bots"]);
+  }
+
+  return { exitCode: report.ok ? 0 : 1, report };
+}

package/lib/foundry.mjs

@@ -0,0 +1,114 @@
+/**
+ * Foundry cast helpers for setup (address resolve + key export).
+ * Never logs private keys.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { spawnSync } from "node:child_process";
+import { getAddress } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { normalizePrivateKey } from "./resolve.mjs";
+import { parseCastWalletList } from "./setup-detect.mjs";
+
+/**
+ * @param {{ castBin?: string, spawn?: typeof spawnSync }} [opts]
+ */
+export function listFoundryAccounts(opts = {}) {
+  const spawn = opts.spawn ?? spawnSync;
+  const castBin = opts.castBin ?? "cast";
+  const result = spawn(castBin, ["wallet", "list"], {
+    encoding: "utf8",
+    shell: false,
+  });
+  if (result.error || result.status !== 0) {
+    return { available: false, accounts: [] };
+  }
+  return { available: true, accounts: parseCastWalletList(result.stdout ?? "") };
+}
+
+/**
+ * Resolve 0x address for a Foundry account name.
+ * Uses inherit stdio so unlock prompts work when interactive.
+ *
+ * @param {string} account
+ * @param {{ castBin?: string, spawn?: typeof spawnSync, inheritStdio?: boolean }} [opts]
+ * @returns {string} checksummed address
+ */
+export function resolveFoundryAddress(account, opts = {}) {
+  const spawn = opts.spawn ?? spawnSync;
+  const castBin = opts.castBin ?? "cast";
+  const inherit = opts.inheritStdio !== false;
+  const result = spawn(castBin, ["wallet", "address", account], {
+    encoding: "utf8",
+    shell: false,
+    stdio: inherit ? ["inherit", "pipe", "inherit"] : "pipe",
+  });
+  if (result.error) {
+    throw new Error(`cast failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const err = (result.stderr || result.stdout || "").trim();
+    throw new Error(
+      err || `cast wallet address ${account} failed (status ${result.status})`,
+    );
+  }
+  const line = String(result.stdout ?? "")
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .find((l) => /^0x[0-9a-fA-F]{40}$/.test(l));
+  if (!line) {
+    throw new Error(`Could not parse address from cast wallet address ${account}`);
+  }
+  return getAddress(line);
+}
+
+/**
+ * Export Foundry account private key to destPath (mode 0o600).
+ * Does not print the key. Unlock prompts via inherit stdio when interactive.
+ *
+ * @param {string} account
+ * @param {string} destPath
+ * @param {{ castBin?: string, spawn?: typeof spawnSync, inheritStdio?: boolean }} [opts]
+ * @returns {{ path: string, address: string }}
+ */
+export function exportFoundryKey(account, destPath, opts = {}) {
+  const spawn = opts.spawn ?? spawnSync;
+  const castBin = opts.castBin ?? "cast";
+  const inherit = opts.inheritStdio !== false;
+  const result = spawn(castBin, ["wallet", "private-key", account], {
+    encoding: "utf8",
+    shell: false,
+    stdio: inherit ? ["inherit", "pipe", "inherit"] : "pipe",
+  });
+  if (result.error) {
+    throw new Error(`cast failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const err = (result.stderr || "").trim();
+    throw new Error(
+      err || `cast wallet private-key ${account} failed (status ${result.status})`,
+    );
+  }
+  const raw = String(result.stdout ?? "")
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .find((l) => l.length > 0);
+  if (!raw) {
+    throw new Error("cast returned empty private key");
+  }
+  const key = normalizePrivateKey(raw);
+  const address = privateKeyToAccount(key).address;
+
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, `${key}\n`, { mode: 0o600 });
+  return { path: destPath, address };
+}
+
+/**
+ * Default operator key path under clanker home.
+ * @param {string} home
+ */
+export function defaultOperatorKeyPath(home) {
+  return `${home.replace(/\/$/, "")}/op.key`;
+}

package/lib/openclaw-wire.mjs

@@ -0,0 +1,145 @@
+/**
+ * Merge / create ~/.openclaw/openclaw.json channels.mqtt from clanker profile.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { harnessSnippet } from "./profile.mjs";
+
+/** Current published OpenClaw plugin pins for closed-beta invite. */
+export const OPENCLAW_PLUGIN_PIN = "2026.7.29";
+
+/**
+ * @param {string} [openclawHome]
+ */
+export function openclawConfigPath(openclawHome = join(homedir(), ".openclaw")) {
+  return join(openclawHome, "openclaw.json");
+}
+
+/**
+ * Ensure mqtt + mqtt-tools are in plugins.enabled.
+ * @param {object} cfg
+ */
+export function ensureMqttPlugins(cfg) {
+  const out = { ...cfg };
+  const plugins = { ...(out.plugins ?? {}) };
+  const enabled = Array.isArray(plugins.enabled) ? [...plugins.enabled] : [];
+  for (const id of ["mqtt", "mqtt-tools"]) {
+    if (!enabled.includes(id)) enabled.push(id);
+  }
+  plugins.enabled = enabled;
+  out.plugins = plugins;
+  return out;
+}
+
+/**
+ * Wire channels.mqtt into openclaw.json.
+ *
+ * @param {{
+ *   botId: string,
+ *   operatorId: string,
+ *   network: { rpc: string, registry: string|null, brokerUrl?: string, mqttAuthServiceUrl?: string },
+ *   keyPath?: string|null,
+ *   openclawHome?: string,
+ * }} opts
+ */
+export function wireOpenClawMqtt(opts) {
+  const openclawHome = opts.openclawHome ?? join(homedir(), ".openclaw");
+  const cfgPath = openclawConfigPath(openclawHome);
+  mkdirSync(openclawHome, { recursive: true });
+
+  const mqtt = harnessSnippet({
+    botId: opts.botId,
+    operatorId: opts.operatorId,
+    network: opts.network,
+  });
+  if (!mqtt.registryAddress) {
+    mqtt.registryAddress = "0x0000000000000000000000000000000000000000";
+  }
+  if (opts.keyPath) {
+    mqtt.privateKeyFile = opts.keyPath;
+  }
+
+  let created = false;
+  let cfg;
+  if (!existsSync(cfgPath)) {
+    created = true;
+    cfg = {
+      plugins: { enabled: ["mqtt", "mqtt-tools"] },
+      channels: { mqtt },
+    };
+  } else {
+    cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+    cfg = ensureMqttPlugins(cfg);
+    const channels = { ...(cfg.channels ?? {}) };
+    const prev = channels.mqtt && typeof channels.mqtt === "object" ? channels.mqtt : {};
+    channels.mqtt = { ...prev, ...mqtt };
+    cfg.channels = channels;
+  }
+
+  writeFileSync(cfgPath, `${JSON.stringify(cfg, null, 2)}\n`, "utf8");
+  return {
+    created,
+    path: cfgPath,
+    channelsMqtt: cfg.channels.mqtt,
+    pluginPin: OPENCLAW_PLUGIN_PIN,
+  };
+}
+
+/**
+ * Human checklist lines after wiring.
+ * @param {{ botId: string, channelsMqtt: object, pluginPin: string }} opts
+ */
+export function hubConnectChecklist(opts) {
+  const pin = opts.pluginPin ?? OPENCLAW_PLUGIN_PIN;
+  return [
+    "Your bot login is already wired — install plugins and restart OpenClaw.",
+    `openclaw plugins install @clanker-chain/mqtt-channel-plugin@${pin}`,
+    `openclaw plugins install @clanker-chain/mqtt-tools@${pin}`,
+    "Enable plugin ids mqtt + mqtt-tools (already set in openclaw.json if we wired it)",
+    `CONNECT broker: ${opts.channelsMqtt?.brokerUrl ?? "mqtts://mqtt.clanker-chain.com:8883"}`,
+    `Ask hub operator to allow bot_id "${opts.botId}" in france dmPolicy / allowFrom`,
+    "DM openclaw.france.prod-1 to smoke the mesh",
+  ];
+}
+
+/**
+ * Plain-language card: what the bot uses vs operator mint key.
+ * @param {{
+ *   botId: string,
+ *   operatorId: string,
+ *   keyPath: string,
+ *   openclawPath: string,
+ *   created?: boolean,
+ * }} opts
+ * @returns {string[]}
+ */
+export function botIdentityCard(opts) {
+  const openclawState = opts.created
+    ? `${opts.openclawPath} (channels.mqtt created)`
+    : `${opts.openclawPath} (channels.mqtt updated)`;
+  return [
+    "Bot identity (what OpenClaw uses to CONNECT):",
+    `bot id:     ${opts.botId}`,
+    `operator:   ${opts.operatorId}`,
+    `bot key:    ${opts.keyPath}`,
+    `openclaw:   ${openclawState}`,
+    "Do not give the bot ~/.clanker/op.key — that key is only for mint/transfer.",
+  ];
+}
+
+/**
+ * Structured bot_identity for --json mint output.
+ * @param {{ botId: string, keyPath: string, openclawConfigPath: string }} opts
+ */
+export function botIdentityJson(opts) {
+  return {
+    botId: opts.botId,
+    keyPath: opts.keyPath,
+    openclawConfigPath: opts.openclawConfigPath,
+    warnOperatorKey:
+      "Do not give the bot ~/.clanker/op.key — that key is only for mint/transfer.",
+  };
+}
+

package/lib/operator-key.mjs

@@ -0,0 +1,50 @@
+/**
+ * Consumer-path operator key helpers (generate local op.key).
+ * Never logs private keys.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import { defaultOperatorKeyPath } from "./foundry.mjs";
+
+export { defaultOperatorKeyPath };
+
+/** Coinbase Developer Platform faucet UI (Base Sepolia). */
+export const BASE_SEPOLIA_FAUCET_URL =
+  "https://portal.cdp.coinbase.com/products/faucet";
+
+/**
+ * Generate a new secp256k1 key and write it to destPath (mode 0o600).
+ * Does not print the key.
+ *
+ * @param {string} destPath
+ * @param {{ force?: boolean }} [opts]
+ * @returns {{ path: string, address: string }}
+ */
+export function generateOperatorKeyFile(destPath, opts = {}) {
+  if (existsSync(destPath) && !opts.force) {
+    throw new Error(
+      `Key file already exists: ${destPath} (pass --force to overwrite)`,
+    );
+  }
+  const key = generatePrivateKey();
+  const address = privateKeyToAccount(key).address;
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, `${key}\n`, { mode: 0o600 });
+  return { path: destPath, address };
+}
+
+/**
+ * Plain-language next steps after creating an operator key on Sepolia.
+ * @param {{ address: string, label?: string }} opts
+ */
+export function consumerFundHints(opts) {
+  const mintLabel = opts.label ? ` ${opts.label}` : "";
+  return [
+    `Your operator address is ${opts.address} — fund it with Base Sepolia ETH: ${BASE_SEPOLIA_FAUCET_URL}`,
+    "clanker doctor",
+    `clanker operator mint${mintLabel} --yes`,
+    "clanker bot mint <bot_label> --yes",
+  ];
+}

package/lib/profile.mjs

@@ -17,11 +17,14 @@ export const ANVIL_DEFAULT_ADDRESS = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
 export const SEPOLIA_REGISTRY = "0xD650467f9D7A20f37E55ec23Ca1c711598f97958";
 
 /**
- * Safe floor for Sepolia getLogs (before registry deploy). Documented so scans
- * stay cheap; bump only if you redeploy the registry earlier.
+ * Safe floor for Sepolia getLogs (before registry deploy). Use for full historical
+ * scans via --from-block; default preset uses the faster public-RPC floor below.
  */
 export const SEPOLIA_FROM_BLOCK = 35_000_000n;
 
+/** Default Sepolia fromBlock for public RPC (faster whoami/bots scans). */
+export const SEPOLIA_FAST_FROM_BLOCK = 46_000_000n;
+
 export const PRESETS = {
   local: {
     preset: "local",
@@ -37,7 +40,7 @@ export const PRESETS = {
     chainRpcUrl: "https://sepolia.base.org",
     brokerUrl: "mqtts://mqtt.clanker-chain.com:8883",
     mqttAuthServiceUrl: "https://mqtt-auth.clanker-chain.com",
-    fromBlock: SEPOLIA_FROM_BLOCK,
+    fromBlock: SEPOLIA_FAST_FROM_BLOCK,
   },
 };
 
@@ -63,7 +66,7 @@ export function openclawKeysDir() {
 
 /**
  * @param {string} presetName
- * @param {{ force?: boolean, registryAddress?: string|null, home?: string }} [opts]
+ * @param {{ force?: boolean, registryAddress?: string|null, home?: string, fromBlock?: bigint|string|number }} [opts]
  */
 export function initProfile(presetName, opts = {}) {
   const name = String(presetName || "").toLowerCase();
@@ -79,13 +82,15 @@ export function initProfile(presetName, opts = {}) {
   }
   mkdirSync(home, { recursive: true });
   const preset = PRESETS[name];
+  const fromBlock =
+    opts.fromBlock != null ? BigInt(opts.fromBlock) : preset.fromBlock;
   const config = {
     preset: preset.preset,
     registryAddress: opts.registryAddress ?? preset.registryAddress,
     chainRpcUrl: preset.chainRpcUrl,
     brokerUrl: preset.brokerUrl,
     mqttAuthServiceUrl: preset.mqttAuthServiceUrl,
-    fromBlock: preset.fromBlock.toString(),
+    fromBlock: fromBlock.toString(),
   };
   if (name === "local" && !config.registryAddress) {
     // Placeholder until chain deploy; operator must set after forge deploy.
@@ -120,8 +125,9 @@ export function loadOperator(home = clankerHome()) {
 }
 
 /**
- * Write operator profile (label + owner + key pointer). Never stores hex keys.
- * @param {{ label: string, owner: string, key?: { type: 'env'|'keyFile', value?: string } }} op
+ * Write operator profile (label + owner + optional key pointer). Never stores hex keys.
+ * Omit `key` (or pass null) for a read-only profile; mint/revoke still need a pointer later.
+ * @param {{ label: string, owner: string, key?: { type: 'env'|'keyFile', value?: string }|null }} op
  * @param {string} [home]
  */
 export function writeOperator(op, home = clankerHome()) {
@@ -130,8 +136,10 @@ export function writeOperator(op, home = clankerHome()) {
   const out = {
     label: op.label,
     owner: op.owner,
-    key: op.key ?? { type: "env", value: "OPERATOR_PRIVATE_KEY" },
   };
+  if (op.key != null) {
+    out.key = op.key;
+  }
   writeFileSync(path, `${JSON.stringify(out, null, 2)}\n`, { mode: 0o600 });
   return { path, operator: out };
 }
@@ -182,7 +190,7 @@ export function resolveNetwork(argv = [], opts = {}) {
   }
 
   if (fromBlock == null) {
-    fromBlock = isLocalRpc(rpc) ? 0n : SEPOLIA_FROM_BLOCK;
+    fromBlock = isLocalRpc(rpc) ? 0n : SEPOLIA_FAST_FROM_BLOCK;
   }
 
   return {

package/lib/resolve.mjs

@@ -3,6 +3,7 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
+import { getAddress } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import {
   ANVIL_DEFAULT_PRIVATE_KEY,
@@ -174,8 +175,63 @@ export function resolveForRead(argv = [], opts = {}) {
   if (!network.registry || !/^0x[0-9a-fA-F]{40}$/.test(network.registry)) {
     throw new Error(
       "REGISTRY_ADDRESS or --registry is required (0x + 40 hex). " +
-        "Run `clanker init --preset sepolia` or set registry after `clanker chain deploy`.",
+        "Run `clanker init --preset sepolia` or `clanker setup`, or set registry after deploy.",
     );
   }
   return network;
 }
+
+/**
+ * Resolve address for read-only commands.
+ * Order: --address > signing key > operator.json owner > error (point at setup).
+ *
+ * @param {string[]} argv
+ * @param {{ home?: string, env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ address: string, source: string, network: object }}
+ */
+export function resolveReadIdentity(argv = [], opts = {}) {
+  const network = resolveForRead(argv, opts);
+  const home = opts.home ?? network.home;
+
+  let addressFlag = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--address" && argv[i + 1] && !argv[i + 1].startsWith("--")) {
+      addressFlag = argv[++i];
+    }
+  }
+  if (addressFlag) {
+    return {
+      address: getAddress(addressFlag),
+      source: "--address",
+      network,
+    };
+  }
+
+  try {
+    const resolved = resolveOperatorKey(argv, { ...opts, home });
+    return {
+      address: resolved.address,
+      source: resolved.source,
+      network: resolved.network,
+    };
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    if (!/private key required|Anvil account #0|Key file not found|Profile keyFile/i.test(msg)) {
+      throw err;
+    }
+  }
+
+  const operator = loadOperator(home);
+  if (operator?.owner && /^0x[0-9a-fA-F]{40}$/.test(operator.owner)) {
+    return {
+      address: getAddress(operator.owner),
+      source: "profile owner",
+      network,
+    };
+  }
+
+  throw new Error(
+    "No operator identity configured. Run `clanker setup`, pass --address 0x…, " +
+      "or set a signing key (OPERATOR_PRIVATE_KEY / --key-file / operator.json key pointer).",
+  );
+}